Obsidian MCP Server

English | 中文文档（机翻）

This Obsidian plugin runs a local MCP (Model Context Protocol) server, allowing external applications (like AI assistants, scripts, or other tools) to interact with your Obsidian vault through a standardized interface.

Features

• Local MCP Server: Runs an SSE-based MCP server on a configurable port.
• Vault Indexing for Semantic Search:
  • Indexes the content of your Markdown notes into an Orama vector database.
  • Uses a configurable OpenAI-compatible embedding model (e.g., OpenAI, local Ollama models via compatible endpoints) to generate embeddings.
  • Allows configuration of text chunking parameters (size, overlap, separators).
  • Supports excluding specific files or patterns from indexing using .gitignore syntax.
• Obsidian Integration:
  • Commands: Provides commands in the Obsidian command palette to:
    • Start/Stop the MCP Server.
    • Re-index the entire vault (can be time-consuming and potentially costly depending on the embedding provider).
    • Manually save the vector database index.
  • Settings Tab: Offers a dedicated settings panel to configure:
    • Server port and auto-start behavior.
    • Embedding provider details (API endpoint, model name, API key).
    • File exclusion patterns for indexing.
    • Chunking parameters.
    • Connection verification for the embedding provider.
  • Ribbon Icon: Adds a status icon to the Obsidian ribbon indicating whether the MCP server is running or stopped.
  • Internationalization: Supports English and Chinese interface languages based on Obsidian's language setting.

MCP Tools

• simple_vector_search: Semantic search for notes using vector embeddings.
• count_entries: Counts indexed notes and chunks in the Orama database.
• list_files: Lists files and folders within a specified directory.
• read_file: Reads the content of a specific file.
• create_file: Creates a new file.
• edit_file: Edits a specific range of lines within an existing file.
• delete_file: Deletes a file.
• create_folder: Creates a folder.
• delete_folder: Deletes a folder.

TODO

• Multi-language support (English, Chinese)
• Provide basic file/folder manipulation tools (create, read, edit, delete)
• Add a tool that can generate notes based on Obsidian templates
• Implement search with filtering by metadata (frontmatter)
• Implement live tracking and updating of new notes and edits

Configuration

Access the plugin settings within Obsidian to configure:

1. Server Settings: Port number and whether the server should start automatically with Obsidian.
2. Embedding Model: Provide the URL, model name, and API key for your chosen OpenAI-compatible embedding provider. Verify the connection using the provided button.
3. Vector Store:
   • Define file patterns (like .gitignore) to exclude specific files or folders from indexing. You can copy patterns directly from your vault's .gitignore file.
   • Adjust chunking parameters (size, overlap, separators) if needed, though default values are generally suitable.
4. MCP Tools: Enable or disable individual tools (like read_file, create_folder, etc.) provided by the server via toggles in the settings. A server restart (using the button in the settings) is required for changes to take effect.

Usage

1. Configure: Set up the plugin via the Obsidian settings panel, especially the Embedding Model details.
2. Index Vault: Run the "Re-index Vault (MCP Server)" command from the Obsidian command palette. This is necessary for the simple_vector_search tool to function. Wait for the indexing process to complete (a notification will appear).
3. Start Server: Ensure the MCP server is running. Either enable "Auto Start MCP" in settings or use the "Start MCP Server" command.
4. Connect External Tool: Connect your MCP client (e.g., an AI assistant configured to use MCP) to the server endpoint displayed in the settings (e.g., http://localhost:8080/sse).
5. Utilize Tools: Use the available MCP tools (simple_vector_search, list_files, read_file, etc.) from your connected client to interact with your Obsidian vault.
6. In your favorite MCP capable client, configure MCP to SSE mode and set the endpoint to http://localhost:8080/sse (or the port you configured). Then you can use the tools exposed by this plugin.
7. Stop Server: Use the "Stop MCP Server" command to stop the server when not in use.

Development

This project uses TypeScript. Ensure you have Node.js and npm installed.

1. Clone the repository.
2. Run npm install to install dependencies.
3. Run npm run dev to compile the plugin and watch for changes.
4. Copy the main.js, manifest.json, and styles.css files into your Obsidian vault's .obsidian/plugins/mcp-server/ directory.
5. Reload Obsidian and enable the plugin.

Status & Limitations

This is a work in progress. It is functional and in daily use, but expect rough edges.

Treat the security posture as unreviewed. The server exposes read and write access to your
vault over a local port, so run it only on a machine you trust, and keep the port bound to
localhost. Indexing sends note content to whichever embedding endpoint you configure, which
is a third party unless you point it at a local model.

Issues and pull requests are welcome, and I try to respond quickly.

Known issues

1. File Size Limit: If your vault contains many notes, indexing may fail when the orama.json file exceeds 512MB. Currently there is no workaround except to reduce note/chunk count.

2. Number Storage: OramaDB stores floating point numbers as raw strings, which can rapidly increase database size.