obsidian

This MCP server enables AI models to directly connect to and manage your Obsidian vault through the MCP protocol. It exposes a comprehensive set of core operations for working with notes and folders, including listing, reading, creating, updating, and deleting notes, as well as performing advanced searches and folder management. It also includes powerful features such as intelligent note analysis, auto-backlink generation, and precise patch-based editing to target specific headings or blocks. With the included tools, you can drive Obsidian content manipulation, perform batch operations, and integrate Obsidian with other AI-driven workflows via the MCP client.

To use it, run the server through your preferred method (for example, via npx as shown in the configuration) and point your MCP client to the server with the required environment variables. The client can then invoke core operations like list_notes, read_note, create_note, update_note, delete_note, and search_vault, as well as advanced features like auto_backlink_vault and notes_insight to generate strategic analyses and smart wikilinks. Ensure the Obsidian Local REST API plugin is installed in your Obsidian instance and that you provide the correct vault path, API token, and port so the MCP server can communicate with Obsidian reliably.

Prerequisites

• Node.js (v16 or higher)
• Obsidian desktop application
• Obsidian Local REST API plugin (installed in Obsidian and token generated)

Option A: Remote Install (NPM) — recommended for most users

1. Ensure Node.js is installed.
2. Run the MCP server via npx (no pre-installation required):

{
  "mcpServers": {
    "obsidian-mcp": {
      "command": "npx",
      "args": [
        "@huangyihe/obsidian-mcp"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
        "OBSIDIAN_API_TOKEN": "your_api_token",
        "OBSIDIAN_API_PORT": "27123"
      }
    }
  }
}

Note: First run downloads the package; subsequent runs use cache.

Option B: Local Deploy (more control)

1. Clone the repository and install locally:

git clone https://github.com/newtype-01/obsidian-mcp.git
cd obsidian-mcp
npm install

2. Build (if applicable) and start using npm:

npm run build
cp .env.example .env
# edit .env with your vault path, token, and port
npm start

3. Alternatively, install globally and configure MCP client:

npm install -g @huangyihe/obsidian-mcp

Option C: Docker Deploy (optional)

1. Copy environment file template and adjust values, then start with Docker Compose or Docker run as described in the repo documentation.
2. Example with Docker run (adjust paths and ports):

docker run -d \
  --name obsidian-mcp \
  --env-file .env \
  --network host \
  -v /path/to/vault:/path/to/vault \
  obsidian-mcp

Prerequisites recap are also described in the README under the Installation Options section.

Tips and notes:

• Use the OBSIDIAN_VAULT_PATH, OBSIDIAN_API_TOKEN, and OBSIDIAN_API_PORT environment variables with the OBSIDIAN- prefix for remote npm installations; plain VAULT_PATH or API_TOKEN without the prefix will not work correctly.
• Ensure the Obsidian Local REST API plugin is installed and the token is generated in its settings; the port must match OBSIDIAN_API_PORT.
• If you’re using Docker, you can use docker-compose with an .env file to keep configuration centralized.
• To enable full capability, keep Obsidian and the Local REST API plugin updated to compatible versions.
• The MCP client should reference the exact server name (e.g., obsidian-mcp) defined in your mcp_config to ensure proper routing of requests.