Obsidian 笔记管理 MCP 服务

Obsidian MCP

An MCP (Model Context Protocol) server that connects your LLM to your Obsidian vault. Read, write, search, and organize your notes through natural conversation.

Built on top of the Obsidian Local REST API plugin. This MCP requires Local REST API 5.0.0 or newer and targets 5.2.0.

Background

This project started as a personal tool for managing a D&D campaign in Obsidian — keeping NPCs, session notes, world lore, and plot threads consistent with the help of an LLM. If you've ever wanted an AI that actually knows your vault, can cross-reference your notes, and helps you keep everything coherent across dozens of interlinked documents, that's the itch this scratches.

It's built for personal use, but structured and documented enough to be useful to anyone doing something similar.

Features

• Read & write notes — create, update, append, copy, move, and trash notes
• Search — find notes by filename, path text, structured query, or full-text search across the vault
• Batch operations — read, append, or trash multiple notes in parallel
• Tree view — display vault structure with configurable depth
• Section editing — update content under a specific heading without rewriting the whole note
• Frontmatter — update YAML frontmatter fields (tags, dates, metadata)

Prerequisites

• Obsidian with the Local REST API community plugin installed and enabled; requires Local REST API 5.0.0+
• uv (Python package manager)
• Python 3.13+
• (Optional) Obsidian 1.12+ with the CLI enabled (Settings → General → Advanced → "Command line interface") — required only for get_unresolved_links

Docs

• Setup guide
• Local REST API compatibility notes

Setup

1. Configure the Obsidian plugin

1. Open Obsidian → Settings → Community Plugins
2. Search for Local REST API, install and enable it
3. In the plugin settings, copy your API key and note the port (default 27123)

2. Install the MCP server

git clone https://github.com/Vosloo/Obsidian-MCP.git
cd Obsidian-MCP
uv sync

3. Set environment variables

cp .env.example .env

Edit .env:

OBSIDIAN_API_URL=https://127.0.0.1:27124
OBSIDIAN_API_KEY=your_api_key_here

4. Test the connection

uv run obsidian-mcp

If the server starts without errors, you're good to go. Press Ctrl+C to stop it.

To test the MCP manually with the MCP Inspector from the project directory:

npx @modelcontextprotocol/inspector uv run obsidian-mcp

Connecting to your LLM

Claude Desktop

Edit your config file:

• Windows: %APPDATA%\Claude\claude_desktop_config.json
• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the server entry (replace the path with your actual project path):

{
  "mcpServers": {
    "obsidian": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/Obsidian-MCP",
        "run",
        "obsidian-mcp"
      ],
      "env": {
        "OBSIDIAN_API_URL": "https://127.0.0.1:27124",
        "OBSIDIAN_API_KEY": "your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop. The Obsidian tools should appear in the interface.

Claude Code (CLI)

Add to your .claude/settings.json or run:

claude mcp add obsidian -- uv --directory /absolute/path/to/Obsidian-MCP run obsidian-mcp

Set the environment variables in your shell or .env file before launching.

Other MCP clients

Any client that supports the Model Context Protocol can connect. Point it at:

uv --directory /path/to/Obsidian-MCP run obsidian-mcp

The server communicates over stdio.

Available tools

Local REST API 5.x behavior

• Note-content read and write tools accept only paths ending in .md (case-insensitive). They reject attachments and other non-Markdown files before making an API request, preventing accidental binary decoding or text overwrites. Byte-safe listing, move, copy, trash, and directory operations remain available for all vault files. read_image separately accepts PNG, JPEG, WebP, GIF (first frame), BMP, and TIFF attachments. It resizes to a 1568-pixel long edge by default, with a 256 MiB download limit and early JPEG downsampling; full_resolution: true preserves dimensions with a 20 MiB byte limit. SVG, binary writes, and signed-URL tools are not exposed.
• copy_note and move_note default to allow_overwrite: false. Set it to true only when replacing the destination is intentional.
• delete_note, batch_delete_notes, and delete_directory explicitly send permanent=false. Local REST API then follows the deletion destination chosen in Obsidian: the vault .trash folder, system trash, or permanent deletion if the user configured Obsidian itself that way. delete_directory refuses the vault root and reports every trashed or failed file individually.
• update_section accepts reject_if_content_preexists: true for append and prepend. This makes retries fail instead of inserting the same text twice.
• read_note and batch_read_notes return valid JSON. Each Local REST API 5.x note object includes unresolvedLinks; batch results preserve the requested path and report failures individually.
• get_unresolved_links remains the efficient vault-wide aggregator. Its JSON response includes available, filters, link_count, and links. Each link has a vault_reference_count reported by the CLI and filtered sources. The count is explicitly vault-wide because the CLI cannot recalculate reference counts after source filtering.

Troubleshooting

License

MIT