obsidian-mcp-server

An MCP server (Model Context Protocol) for an Obsidian study vault. Gives Claude access to note search, note contents, flashcard creation in the Decks format, and the study planning of the study tracker plugin.

Python, MCP SDK 2.x, stdio transport.

Purpose

So far, the logic lived in two Obsidian plugins:

• Decks (third-party plugin) renders flashcards but doesn't create them — the cards were written by hand.

• Lerntracker (own plugin) manages study progress and study plan, but deliberately doesn't distribute the material across days automatically.

This server closes both gaps: Claude can create cards directly in the existing file format and calculate a study plan that is written back into the Lerntracker's data.json.

Related MCP server: Nexus MCP for Obsidian

Installation

cd ~/Projects/obsidian-mcp-server
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Configuration

Both paths come from environment variables — nothing is hardcoded.

The default for the vault path fits an iCloud-synchronized Obsidian; for a different setup, setting OBSIDIAN_VAULT_PATH is enough.

The Lerntracker path is separately configurable because Obsidian vaults can be nested: if another vault sits in a subfolder, it has its own data.json. The default points to the main vault's.

Tools

All schemas are generated by the SDK from type hints and docstrings — there is no hand-written JSON schema in the code.

Flashcard format

create_flashcard writes exactly the format that the existing cards in the vault use (header paragraph), extended with a wikilink to the source:

---
tags: [decks]
---

## Was ist ein Signal?

Eine zeitabhängige, messbare physikalische Größe.

Quelle: [[01_Physikalische_Schicht]]

The target file results from the course folder of the source note; deck overrides the filename. If the file doesn't exist, it is created with tags: [decks]. A card with an identical front is skipped instead of being created twice.

The study state of Decks lives in a SQLite database, not in the Markdown files. The server doesn't touch it — the FSRS history stays untouched.

Why generate_summary doesn't summarize itself

The server has no language model. It returns the note in structured form (outline, key figures, full text); the summary is written by the model on the client side — i.e., Claude Desktop. It is then saved with save_summary. That's the usual MCP division of roles: the server delivers context and runs actions, the model formulates.

If the server were to summarize itself instead, it would need to call the Anthropic API and would need its own API key.

Study plan logic

generate_study_plan distributes each open subtopic to concrete days:

1. Courses are sorted by exam date — the earliest exam first.

2. Study end = examDate − bufferDays; the buffer days stay free for review.

3. Study days come from settings.weeklyHours (0 = Sunday … 6 = Saturday). Days with 0 hours and all blockedDates are skipped.

4. Each subtopic costs hours_per_subtopic (default 1.5 h) and is placed on the earliest day with remaining capacity. If it doesn't fit into one day, it is split across multiple days — the plugin supports multiple dates.

5. Already checked-off subtopics and those with existing dates remain untouched.

6. Anything that no longer fits before the study end is reported as a warning instead of being silently discarded.

Before each write operation, a backup is created next to the file (data.backup-<Zeitstempel>.json); writing is atomic via a temporary file. dry_run=True only shows the plan.

After writing in Obsidian, press Cmd+R so the plugin reloads.

Resources

The template deliberately uses {+path} (reserved expansion) instead of {path}. Normal template variables don't match slashes — with {path}, any note in a subfolder would silently not be found, and in the vault practically every note sits in a course folder.

Testing locally with the MCP Inspector

The Inspector is started via the SDK's CLI and opens a web interface, in which tools and resources can be called individually. It needs npx (Node.js) and uv.

source .venv/bin/activate && mcp dev main.py

The command outputs a URL like http://localhost:6274 (with an appended session token). Open it in the browser, click Connect on the left, then:

• Tab Tools → List Tools → pick a tool, enter arguments, Run Tool

• Tab Resources → List Resources → click vault://structure

• For the templated resource, enter the URI directly, following the pattern note://<Kursordner>/Flashcards/<Datei>.md

With a different vault:

OBSIDIAN_VAULT_PATH="$HOME/Pfad/zu/deinem/Vault" mcp dev main.py

For trying out the writing tools, a throwaway vault is worth it:

OBSIDIAN_VAULT_PATH=/tmp/testvault mcp dev main.py

Connecting to Claude Desktop

Configuration file: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "/Users/DEIN_NAME/Projects/obsidian-mcp-server/.venv/bin/python",
      "args": ["/Users/DEIN_NAME/Projects/obsidian-mcp-server/main.py"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/Users/DEIN_NAME/Pfad/zu/deinem/Vault"
      }
    }
  }
}

Important: use absolute paths — ~ and $HOME are not expanded here. As command specify the Python from the venv: Claude Desktop starts the server without an activated environment, a bare "python3" would not find the mcp package.

If the file already exists, only insert the "obsidian-vault" entry into the existing mcpServers object. Then fully quit and restart Claude Desktop; the server then appears in the tool menu of the input field.

Security

Every path from a tool or resource call is checked against the vault: absolute paths and .. traversal are rejected, and the resolved target must lie within OBSIDIAN_VAULT_PATH. .obsidian, .git, .trash, .claude and node_modules are excluded from search and structure listing — plugin bundles would otherwise flood the results.

save_summary doesn't overwrite an existing file, create_flashcard doesn't create a duplicate card, and generate_study_plan backs up data.json before writing.

Tested

Against mcp 2.0.0 on Python 3.14: tool schemas, resource templates, stdio handshake with a real ClientSession, path guards, and the writing tools against a throwaway vault (including multi-day split, blocked days, zero-hour weekdays, and the overflow case).

License

MIT — see LICENSE.