Obsidian MCP

What maxkuminov/obsidian-mcp does

maxkuminov/obsidian-mcp gives AI agents MCP access to an Obsidian vault while keeping the underlying memory in ordinary Markdown files. People can open, inspect, edit, search, move, or delete those notes directly in Obsidian. Agents use the same vault as a shared context layer, so notes created during one session can be found by later sessions or by other connected agents.

The server combines three kinds of access: retrieval over note content, traversal of relationships expressed with Obsidian wikilinks, and controlled mutations to notes. A self-describing vault guide helps an agent understand the vault's folder conventions, frontmatter fields, and tags before it reads or writes content.

How it works

A FastAPI application provides the MCP server, with PostgreSQL 16 and pgvector supporting indexed retrieval. Full-text search handles keyword-oriented queries, while semantic search uses configurable embeddings. The supported embedding choices are Ollama's bge-m3 and OpenAI's text-embedding-3-small or text-embedding-3-large.

Wikilinks supply the connections used by graph operations, including neighborhood traversal around a note. Agents decide when to read, search, link, or write; the system does not independently infer memories or maintain them on a schedule.

The deployment can be reached remotely and protected with OAuth 2.0 or a bearer key. This makes the same vault available to clients in different environments, including Claude Code sessions and other MCP-connected agents.

Setup and configuration

The project uses Python 3.12, FastAPI, PostgreSQL 16, and pgvector. A deployment therefore needs a Python 3.12 runtime, a PostgreSQL instance with pgvector, and access to the Obsidian vault that will hold the Markdown notes. Embeddings can be supplied through Ollama with bge-m3 or through OpenAI with one of the supported text-embedding-3 models.

Authentication is part of the deployment model: configure OAuth 2.0 or a bearer key before exposing the service to clients or the wider network. The vault's own layout, frontmatter schema, and tag conventions are discovered through its self-describing guide rather than hard-coded into each agent prompt.

Tools and capabilities

Examples of the exposed operations include:

• semantic_search for concept-based retrieval across notes.
• Full-text search for keyword-oriented lookup.
• read_note to retrieve a note by path.
• Atomic note create, read, update, and delete operations.
• set_frontmatter for structured YAML metadata changes, such as updating tags.
• get_neighborhood to follow wikilink relationships around a note.
• Vault-guide access so agents can learn local organization and metadata conventions.

The structured frontmatter operation changes YAML metadata separately from the note body, which supports clean round-tripping of note content and metadata.

Limitations and notes

The server supplies storage access, search, and graph operations; agents remain responsible for deciding what to remember and when to write it. There is no background extraction, consolidation, or memory-decay process. A fact becomes part of the vault when an agent or person writes a note, and it is removed when someone deletes one.

The design is self-hosted and keeps the human-readable notes in the vault, but the service still needs its PostgreSQL/pgvector backend for indexing and retrieval. Remote access should use the available OAuth 2.0 or bearer-key protections.