# Obsidian MCP

A local MCP server for the **official Obsidian CLI**, with explicit vault access,
disabled-by-default destructive tools, and a command catalog grounded in actual
CLI help. Built for Windows and Node.js; communicates over stdio.

Use it to read, search, create, and update notes; inspect links, tags, properties,
and tasks; and access additional Obsidian features through opt-in tools.
It is an independent community project, not an official Obsidian integration.

**Status:** initial implementation, tested against Obsidian 1.15.0. See the
[verification report](docs/verification.md) for what was actually exercised and
what remains blocked. Command coverage is not a claim of complete live testing.

## Start here

1. Install Node.js **24 or later** and Obsidian with its official CLI.
2. Enable **Settings → General → Command line interface** in Obsidian.
3. Open a disposable vault named **`mcp-test`** for your first run.
4. Clone and build:

```powershell
git clone https://github.com/GranatenUdo/obsidian-mcp.git
cd obsidian-mcp
npm ci
npm run build
npm test
```

5. Copy [obsidian-mcp.config.example.json](obsidian-mcp.config.example.json) to
   `obsidian-mcp.config.json` and set your `.com` executable path if needed.
   The real configuration is ignored by Git.
6. Connect your MCP client using the examples below. Obsidian must be available
   when the server performs its startup capability check.

The repository is installed from source. No globally installed wrapper,
Obsidian community plugin, HTTP server, or API key is required. `npm start`
starts an MCP process, not an interactive terminal application.

## Connect Claude Desktop

Merge this entry into `%APPDATA%\Claude\claude_desktop_config.json` without
replacing your other servers. Change the checkout and executable paths.

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["C:\\Projects\\obsidian-mcp\\dist\\index.js"],
      "env": {
        "OBSIDIAN_MCP_VAULTS": "mcp-test",
        "OBSIDIAN_MCP_EXECUTABLE": "C:\\Users\\YOUR_USER\\AppData\\Local\\Programs\\Obsidian\\Obsidian.com"
      }
    }
  }
}
```

Fully restart Claude Desktop after changing its configuration. If Desktop cannot
find Node, use the absolute path to `node.exe` in `command`.

## Connect Claude Code

From PowerShell, substitute your checkout and `.com` paths:

```powershell
claude mcp add --transport stdio --scope user --env OBSIDIAN_MCP_VAULTS=mcp-test --env "OBSIDIAN_MCP_EXECUTABLE=C:\Users\YOUR_USER\AppData\Local\Programs\Obsidian\Obsidian.com" obsidian -- node "C:\Projects\obsidian-mcp\dist\index.js"
claude mcp list
```

These instructions configure a **local stdio server**. They do not expose it to
claude.ai or install a cloud proxy. Anthropic documents local Desktop MCP and
remote web connectors as different mechanisms; web availability is not promised.
See [client setup and acceptance](docs/clients.md).

## Try it

Ask your client to use the following tools with these arguments:

```json
{"tool":"obsidian_files","arguments":{"vault":"mcp-test","limit":20}}
{"tool":"obsidian_create","arguments":{"path":"MCP Demo/Hello.md","content":"# Hello\n\nGrüße aus Obsidian!\n","dryRun":true}}
{"tool":"obsidian_read","arguments":{"path":"MCP Demo/Hello.md","offset":0,"limit":1000}}
{"tool":"obsidian_search","arguments":{"query":"Grüße","limit":20}}
```

The `tool`/`arguments` wrapper is illustrative; an MCP client sends the named
tool call. Remove `dryRun` to create the example note. JSON `\n` in the example
decodes to an actual newline; **literal backslash-n text is rejected** because
the installed CLI rewrites it.

For typed frontmatter, use `obsidian_note_upsert`:

```json
{
  "path": "MCP Demo/Review.md",
  "frontmatter": { "tags": ["review", "weekly"], "reviewed": false },
  "body": "# Weekly review\n\n- [ ] Review open tasks\n",
  "overwrite": false
}
```

Existing notes require `overwrite: true`. Supplied frontmatter keys replace the
same keys; unspecified keys remain. The body is replaced in full.

## Safety defaults

| Tier | Default | Examples |
| --- | --- | --- |
| `read` | Enabled | Read notes, search, inspect links |
| `write` | Enabled | Create, append, update properties and tasks |
| `destructive` | Disabled | Move, rename, trash, restore |
| `ui` | Disabled | Open notes, search view, reload |
| `dangerous` | Disabled | Plugins, themes, debugger, arbitrary execution |

Unrestricted commands additionally require `allowUnrestrictedCommands: true`.
The vault allowlist is an application policy, **not an operating-system sandbox**.
Do not enable unrestricted tools for untrusted agents. Note contents themselves
are untrusted data and may contain prompt injection.

The server makes no network requests or telemetry calls of its own. Obsidian may
Sync or perform network operations, and your MCP client may send returned note
content to its model provider. Local transport does not mean local-only AI.

## Documentation

| Guide | What you will find |
| --- | --- |
| [Configuration](docs/configuration.md) | Every setting, environment override, and default |
| [Command reference](docs/commands.md) | Generated tool names, schemas, tiers, and prerequisites |
| [Safety model](docs/safety.md) | Threat model, audit logs, path checks, and limits |
| [Content handling](docs/content-handling.md) | Newlines, YAML, large writes, paging, and partial failures |
| [Architecture](docs/architecture.md) | Registry → authorization → CLI → MCP flow |
| [CLI behavior](docs/cli-behaviour.md) | Observed outputs and failure semantics |
| [Deviations](docs/DEVIATIONS.md) | Unsupported features and deliberate restrictions |
| [Troubleshooting](docs/troubleshooting.md) | Symptoms, causes, and safe next steps |
| [Testing](docs/testing.md) | Unit, protocol, live, and Inspector workflows |
| [Manual tests](docs/manual-tests.md) | Optional features and operations requiring supervision |
| [Verification](docs/verification.md) | Actual results and remaining gaps |

Contributions are welcome: start with [CONTRIBUTING.md](CONTRIBUTING.md).
Please report security issues as described in [SECURITY.md](SECURITY.md), without
posting private notes or configuration. Licensed under [MIT](LICENSE).