obsidian-mcp-context

Turn textual Obsidian vault notes into AI-ready context exposed through MCP.

This project does not run an AI model itself. It parses an Obsidian vault and exposes structured context to an MCP-aware AI client. The AI client provides the model; this server provides the vault tools.

Features

• Obsidian Markdown files (.md) by default.
• Optional plain .txt parsing as generic text blocks only.
• Synthetic demo vault under examples/synthetic-vault.
• Deterministic parsing of headings, heading paths, blocks, tasks, wikilinks, tags, and semantic lines.
• File, block, heading, and line-level provenance.
• CLI and MCP tools for listing notes, searching blocks, listing tasks, and fetching note context.

How The Pipeline Works

The intended workflow is:

1. You have an Obsidian vault on disk.
2. You install this package locally.
3. You run the MCP server from this repo.
4. Your MCP client connects to that server.
5. The AI client calls tools such as search_vault_blocks and list_vault_tasks.
6. Each tool call includes a vault_path, so the server knows which vault to parse.
7. The server returns structured JSON with source paths, headings, line numbers, blocks, links, tags, and tasks.
8. The AI client uses that returned context to answer questions or help you work with the vault.

The model can be OpenAI, Anthropic, a local model, or anything else supported by your MCP client. This repo does not currently ask for an API key, configure a model, create embeddings, or talk to a local LLM directly.

Install For Local Development

Clone the repo and install it into a virtual environment:

git clone https://github.com/gavinsomers/obsidian-mcp-context.git
cd obsidian-mcp-context
python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]"

After installation, the local commands are available at:

.venv/bin/obsidian-mcp-context
.venv/bin/obsidian-mcp-context-mcp

Try The Synthetic Vault

The repo includes a small synthetic Obsidian vault at examples/synthetic-vault. Use it first to confirm the parser works before pointing the tools at your own notes.

List notes:

.venv/bin/obsidian-mcp-context --vault examples/synthetic-vault notes

Search parsed blocks:

.venv/bin/obsidian-mcp-context --vault examples/synthetic-vault blocks --text renewal

List unchecked tasks:

.venv/bin/obsidian-mcp-context --vault examples/synthetic-vault tasks --unchecked

The output is JSON. It is intentionally verbose enough for an AI client to cite where each piece of context came from.

Use Your Own Obsidian Vault

Find the absolute path to your vault. For example:

/Users/gavin/Documents/Obsidian/Main Vault

or:

/home/gavman/notes/main-vault

Then run the same CLI commands with your vault path:

.venv/bin/obsidian-mcp-context --vault "/absolute/path/to/your/vault" notes
.venv/bin/obsidian-mcp-context --vault "/absolute/path/to/your/vault" blocks --text "renewal"
.venv/bin/obsidian-mcp-context --vault "/absolute/path/to/your/vault" tasks --unchecked

MCP Server

Start the MCP server manually with:

.venv/bin/obsidian-mcp-context-mcp

Available tools:

• list_vault_notes
• search_vault_blocks
• list_vault_tasks
• get_vault_note_context

Each MCP tool accepts a vault_path argument. That means you do not hard-code a single vault into the server. Your client asks the tool to operate on a specific vault path.

Configure An MCP Client

Add this server to your MCP client configuration. Use absolute paths for both command and cwd.

{
  "command": "/absolute/path/to/obsidian-mcp-context/.venv/bin/obsidian-mcp-context-mcp",
  "args": [],
  "cwd": "/absolute/path/to/obsidian-mcp-context"
}

For this repo checked out at /home/gavman/code/obsidian-mcp-context, the configuration would be:

{
  "command": "/home/gavman/code/obsidian-mcp-context/.venv/bin/obsidian-mcp-context-mcp",
  "args": [],
  "cwd": "/home/gavman/code/obsidian-mcp-context"
}

Once the client is connected, ask it to use the tools with your vault path. For example:

Use the Obsidian MCP context tools with vault_path "/home/gavman/notes/main-vault".
List my unchecked tasks related to renewal.

or:

Use vault_path "/home/gavman/notes/main-vault".
Search my vault for blocks about Project Atlas and return the source note and line numbers.

Tool Inputs

list_vault_notes

• vault_path: path to the Obsidian vault.
• limit: maximum notes to return. Defaults to 100.

search_vault_blocks

• vault_path: path to the Obsidian vault.
• text: optional case-insensitive search text.
• source_path: optional filter for vault-relative source paths.
• heading: optional filter for heading paths.
• limit: maximum blocks to return. Defaults to 25.

list_vault_tasks

• vault_path: path to the Obsidian vault.
• checked: optional completion filter. Use false for open tasks.
• text: optional case-insensitive search text.
• source_path: optional filter for vault-relative source paths.
• limit: maximum tasks to return. Defaults to 50.

get_vault_note_context

• vault_path: path to the Obsidian vault.
• source_path: vault-relative note path, such as Projects/Atlas.md.

Current AI Boundary

This repo is deliberately model-agnostic right now.

It does:

• Parse local Markdown notes.
• Preserve provenance.
• Return structured context through CLI and MCP tools.
• Let an MCP client decide how to use that context.

It does not:

• Ask for an OpenAI API key.
• Ask for an Anthropic API key.
• Connect to Ollama or another local model.
• Generate embeddings.
• Store vectors.
• Chat with your notes by itself.

If you want OpenAI, Anthropic, or local LLM support, configure that in your MCP client. The client supplies the model; this package supplies the Obsidian vault context.

Development

.venv/bin/python -m pytest