# Obsidian Knowledge MCP

> A private-by-default MCP server that lets AI clients search, read, and traverse a local Obsidian vault without uploading it to an external index.

**Status:** public-safe prototype · **Role:** independent design and implementation · **Origin:** sanitized reconstruction of a knowledge-retrieval component built during a 2026 summer automation project.

[中文说明](README.zh-CN.md) · [Bilingual docs index](docs/README.md) · [Architecture](docs/ARCHITECTURE.md) · [Evaluation](docs/EVALUATION.md) · [Failure analysis](docs/FAILURE_ANALYSIS.md)

## What it demonstrates

- Five read-only MCP tools for discovery, evidence reading, graph navigation, and vault health.
- Transparent ranking: exact phrase + title/heading boosts + English tokens + Chinese 2-grams.
- Source-grounded results with vault-relative paths, headings, excerpts, scores, and pagination.
- Local privacy boundary: no cloud index, no API key, hidden folders excluded, path traversal rejected.
- MCP Python SDK 2.x, structured output, annotations, in-memory integration tests, and a synthetic demo vault.

## Tools

| Tool | Workflow role |
|---|---|
| `obsidian_search_notes` | Find relevant note sections with filters and pagination |
| `obsidian_read_note` | Read one note or an exact heading as evidence |
| `obsidian_list_notes` | Browse by folder prefix or tag |
| `obsidian_find_backlinks` | Follow Obsidian `[[wikilinks]]` back to related notes |
| `obsidian_vault_stats` | Inspect vault size, link count, and top tags |

All tools are declared read-only and closed-world. The server never edits the vault.

## Quick start

Requirements: Python 3.10+ and [`uv`](https://docs.astral.sh/uv/).

```bash
git clone <your-repository-url>
cd obsidian-knowledge-mcp
uv sync --extra dev
export OBSIDIAN_VAULT_PATH="/absolute/path/to/your/Obsidian Vault"
uv run obsidian-knowledge-mcp
```

The process uses stdio and waits for an MCP client. For an interactive inspection UI:

```bash
uv run mcp dev src/obsidian_knowledge_mcp/server.py
```

Run the included sample vault ([English demo](demo/README.md) · [中文演示](demo/README.zh-CN.md)):

```bash
export OBSIDIAN_VAULT_PATH="$PWD/examples/sample_vault"
uv run mcp dev src/obsidian_knowledge_mcp/server.py
```

## Client configuration

Use an absolute path to the repository and vault:

```json
{
  "mcpServers": {
    "obsidian-knowledge": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/obsidian-knowledge-mcp",
        "run",
        "obsidian-knowledge-mcp"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/Obsidian Vault"
      }
    }
  }
}
```

## Test and lint

```bash
uv run pytest
uv run ruff check .
```

The tests cover ranking, Chinese retrieval, filters, pagination, section reads, backlink resolution, hidden-folder exclusion, traversal prevention, tool discovery, and structured MCP responses.

## Privacy and security

- Keep private vaults local; do not commit them to this repository.
- Only Markdown under `OBSIDIAN_VAULT_PATH` is scanned.
- `.obsidian`, `.git`, `.trash`, `node_modules`, and `attachments` are excluded by default.
- Returned paths are vault-relative, not absolute.
- The project contains only synthetic sample notes. It does not contain employer data, chat exports, credentials, or production identifiers.

## Current limitations

- Ranking is lexical, not embedding-based; distant paraphrases may need query reformulation.
- Wiki-link resolution does not implement every Obsidian alias or duplicate-title edge case.
- The index is rebuilt per tool call in v0.1; a watched incremental cache is a future optimization.
- The server trusts the local OS user who launches it. It is not a multi-tenant remote service.

## Project map

```text
src/obsidian_knowledge_mcp/  search engine and MCP adapter
tests/                       unit and in-memory MCP integration tests
examples/sample_vault/       synthetic, reproducible demo data
eval/                        stable evaluation questions
docs/                        architecture, case, PRD, evaluation, failures
```

## License

MIT. See [LICENSE](LICENSE).