# obsidian-mcp

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes an Obsidian (Markdown) vault to any MCP client (Claude Desktop, Claude Code, Cursor). Ask your assistant to search your notes, read a specific note, or list your tags, and it queries the vault directly through typed MCP tools.

## Tools

| Tool | Description |
|---|---|
| `list_notes` | List every Markdown note as vault-relative paths |
| `search_notes(query, limit=20)` | Case-insensitive substring search; returns `{path, line, snippet}` hits |
| `read_note(path)` | Read one note by its vault-relative path |
| `list_tags` | Every tag in the vault with its count, from frontmatter and inline `#tags` |

All tools are read-only and refuse any path outside the vault root.

## Install

```bash
git clone https://github.com/<your-username>/obsidian-mcp.git
cd obsidian-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```

## Configure in an MCP client

Point the client at the server and set `VAULT_PATH` to your vault root. Example for Claude Desktop (`claude_desktop_config.json`) or Claude Code:

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp",
      "env": { "VAULT_PATH": "/absolute/path/to/your/vault" }
    }
  }
}
```

Restart the client. Ask it: *"search my vault for retrieval"* or *"list my tags."*

## Develop

```bash
pytest            # run the unit tests
VAULT_PATH=/path/to/vault obsidian-mcp   # run the server on stdio
```

The core vault logic lives in `src/obsidian_mcp/vault.py` (pure functions, fully unit-tested) and is kept separate from the MCP wiring in `server.py`, so the logic can be tested without an MCP client.

## Roadmap

- Write tools (append to a note, create from template) behind an opt-in flag
- Expose notes as MCP resources and add reusable prompts
- Streamable-HTTP transport for remote use
- Tag-filtered and frontmatter-field search

## License

MIT