obsidian-mcp-server — Claude Code MCP server: features and setup
Connects AI coding agents to an Obsidian workspace, enabling targeted edits to headings, frontmatter attributes, tags, and note content.
claude mcp add --env OBSIDIAN_API_KEY=<OBSIDIAN_API_KEY> --env OBSIDIAN_BASE_URL=<OBSIDIAN_BASE_URL> --env OBSIDIAN_VERIFY_SSL=<OBSIDIAN_VERIFY_SSL> --env OBSIDIAN_REQUEST_TIMEOUT_MS=<OBSIDIAN_REQUEST_TIMEOUT_MS> --env OBSIDIAN_ENABLE_COMMANDS=<OBSIDIAN_ENABLE_COMMANDS> --transport stdio obsidian-mcp-server -- npx -y obsidian-mcp-serverWhat obsidian-mcp-server does
This server bridges coding agents with an Obsidian workspace by querying the Local REST API community extension. It exposes capabilities to read complete files, inspect isolated document sections, and run searches using plain text matching, JSONLogic rules, or Omnisearch.
The package bundles 14 tools and 3 resources. Models can append snippets under target headings, patch frontmatter properties, run regex replacements, and trigger command-palette actions. Scoping read permissions to specific directories via OBSIDIAN_READ_PATHS helps restrict agent access to sensitive files.
A running Obsidian instance with an active Local REST API setup and an OBSIDIAN_API_KEY token are mandatory before starting the server.
What it helps with
- search notes using JSONLogic filters and frontmatter criteria
- append content under a specific heading without rewriting the note
- update or remove individual metadata keys in frontmatter
- inspect vault tags alongside their total occurrence counts
Example prompts for the agent
- Find all notes in my Obsidian vault containing the tag #architecture.
- Append a new task item under the 'Action Items' section in
meeting-notes.md. - Inspect the current Obsidian connection status using
obsidian://status.
How to install obsidian-mcp-server
Platform CLI
claude mcp add --env OBSIDIAN_API_KEY=<OBSIDIAN_API_KEY> --env OBSIDIAN_BASE_URL=<OBSIDIAN_BASE_URL> --env OBSIDIAN_VERIFY_SSL=<OBSIDIAN_VERIFY_SSL> --env OBSIDIAN_REQUEST_TIMEOUT_MS=<OBSIDIAN_REQUEST_TIMEOUT_MS> --env OBSIDIAN_ENABLE_COMMANDS=<OBSIDIAN_ENABLE_COMMANDS> --transport stdio obsidian-mcp-server -- npx -y obsidian-mcp-serverReplace <…> with your own values. 11 more environment variables are in the server README
Platform CLI
codex mcp add obsidian-mcp-server --env OBSIDIAN_API_KEY=<OBSIDIAN_API_KEY> --env OBSIDIAN_BASE_URL=<OBSIDIAN_BASE_URL> --env OBSIDIAN_VERIFY_SSL=<OBSIDIAN_VERIFY_SSL> --env OBSIDIAN_REQUEST_TIMEOUT_MS=<OBSIDIAN_REQUEST_TIMEOUT_MS> --env OBSIDIAN_ENABLE_COMMANDS=<OBSIDIAN_ENABLE_COMMANDS> -- npx -y obsidian-mcp-serverReplace <…> with your own values. 11 more environment variables are in the server README
Config file
{
"mcpServers": {
"obsidian-mcp-server": {
"command": "npx",
"args": [
"-y",
"obsidian-mcp-server"
],
"env": {
"OBSIDIAN_API_KEY": "<OBSIDIAN_API_KEY>",
"OBSIDIAN_BASE_URL": "<OBSIDIAN_BASE_URL>",
"OBSIDIAN_VERIFY_SSL": "<OBSIDIAN_VERIFY_SSL>",
"OBSIDIAN_REQUEST_TIMEOUT_MS": "<OBSIDIAN_REQUEST_TIMEOUT_MS>",
"OBSIDIAN_ENABLE_COMMANDS": "<OBSIDIAN_ENABLE_COMMANDS>"
}
}
}
}Replace <…> with your own values. 11 more environment variables are in the server README
Config file
{
"servers": {
"obsidian-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"obsidian-mcp-server"
],
"env": {
"OBSIDIAN_API_KEY": "<OBSIDIAN_API_KEY>",
"OBSIDIAN_BASE_URL": "<OBSIDIAN_BASE_URL>",
"OBSIDIAN_VERIFY_SSL": "<OBSIDIAN_VERIFY_SSL>",
"OBSIDIAN_REQUEST_TIMEOUT_MS": "<OBSIDIAN_REQUEST_TIMEOUT_MS>",
"OBSIDIAN_ENABLE_COMMANDS": "<OBSIDIAN_ENABLE_COMMANDS>"
}
}
}
}Replace <…> with your own values. 11 more environment variables are in the server README
Platform CLI
gemini mcp add -e OBSIDIAN_API_KEY=<OBSIDIAN_API_KEY> -e OBSIDIAN_BASE_URL=<OBSIDIAN_BASE_URL> -e OBSIDIAN_VERIFY_SSL=<OBSIDIAN_VERIFY_SSL> -e OBSIDIAN_REQUEST_TIMEOUT_MS=<OBSIDIAN_REQUEST_TIMEOUT_MS> -e OBSIDIAN_ENABLE_COMMANDS=<OBSIDIAN_ENABLE_COMMANDS> obsidian-mcp-server npx -y obsidian-mcp-serverReplace <…> with your own values. 11 more environment variables are in the server README
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about obsidian-mcp-server
How to install obsidian-mcp-server in Claude Code?
Run claude mcp add obsidian-mcp-server -e OBSIDIAN_API_KEY=<OBSIDIAN_API_KEY> -- npx -y obsidian-mcp-server with your secret key.
What does obsidian-mcp-server do?
It allows LLM assistants to read, search, append, and perform pinpoint edits on notes, tags, and frontmatter inside Obsidian.
What prerequisites are needed inside Obsidian?
You need the Local REST API community plugin installed and active in Obsidian, with its generated token passed into OBSIDIAN_API_KEY.
