Zettelkasten

You run a Model Context Protocol server that enables you to create, link, and explore atomic notes through MCP-compatible clients like Claude. It stores notes in Markdown, builds a navigable knowledge graph, and provides a practical, document-driven way to manage ideas and insights with strong linking and search capabilities.

How to use

You operate the server as a local, standard Python process and connect clients via MCP. Start the server with your preferred data directories and database, then configure your MCP client to reach the server using a local command. Use the client to create notes, link them, search, and explore your Zettelkasten through the bidirectional relationships that form a connected knowledge graph. You will manage notes, links, tags, and note types, and you can run the server either with a SQLite database bundled with the project or with a PostgreSQL/MySQL/MSSQL backend if you configure the database URL.

How to install

Prerequisites you need before installing are Python and a supported package manager for your preferred installation path.

Install via Smithery to get a Claude-enabled MCP client integration set up automatically.

npx -y @smithery/cli install zettelkasten-mcp --client claude

Install via uvx for quick local setup using the GitHub source.

uvx --from=git+https://github.com/entanglr/zettelkasten-mcp zettelkasten-mcp --notes-dir ./data/notes --database ./data/db/zettelkasten.db

Alternatively, install via pipx for a native Python environment and run the server from the installed package.

pipx install "git+https://github.com/entanglr/zettelkasten-mcp.git" 
# or when published on PyPI
# pipx install zettelkasten-mcp

Run the server with the notes directory and database specified.

zettelkasten-mcp --notes-dir ./data/notes --database ./data/db/zettelkasten.db

If you prefer a PostgreSQL backend, install the PostgreSQL extras and point to a SQLAlchemy URL.

pip install "zettelkasten-mcp[postgresql]"
export ZETTELKASTEN_DATABASE="postgresql+psycopg://user:password@localhost:5432/zettelkasten"

Additional configuration and usage notes

Configuration can be adjusted via a .env file. Copy the example and modify to set your database backend and directories.

cp .env.example .env

For PostgreSQL or MySQL, install the corresponding extras and provide a SQLAlchemy-compatible URL in ZETTELKASTEN_DATABASE.

export ZETTELKASTEN_DATABASE="postgresql+psycopg://user:password@localhost:5432/zettelkasten"
# or for MySQL
export ZETTELKASTEN_DATABASE="mysql+pymysql://user:password@localhost:3306/zettelkasten"

Security and maintenance

Regularly back up your Markdown notes and the database index. The index can be rebuilt from Markdown files if needed. When updating configuration, restart the server to apply changes.

Examples

Create a small Zettelkasten network focused on the Zettelkasten method itself, with atomic notes, links, and tags to demonstrate structure and exploration.

Available tools

zk_create_note

Create a new note with a title, content, and optional tags.

zk_get_note

Retrieve a specific note by ID or title.

zk_update_note

Update an existing note's content or metadata.

zk_delete_note

Delete a note.

zk_create_link

Create links between notes.

zk_remove_link

Remove links between notes.

zk_search_notes

Search for notes by content, tags, or links.

zk_get_linked_notes

Find notes linked to a specific note.

zk_get_all_tags

List all tags in the system.

zk_find_similar_notes

Find notes similar to a given note.

zk_find_central_notes

Find notes with the most connections.

zk_find_orphaned_notes

Find notes with no connections.

zk_list_notes_by_date

List notes by creation or update date.

zk_rebuild_index

Rebuild the database index from Markdown files.