zettelkasten

This MCP server implements a Zettelkasten knowledge management workflow. It exposes a set of note types (fleeting, literature, permanent, structure, hub) and a rich graph of semantic links (reference, extends, refines, contradicts, questions, supports, related). The server stores notes as Markdown files with YAML frontmatter (the source of truth) and builds a fast index in SQLite to support search and rapid traversal by Claude or other MCP clients. Users can create atomic notes, connect them via bidirectional links, tag notes for organization, and explore relationships across topics. The dual storage approach enables editing Markdown files directly while maintaining a searchable index for AI-assisted navigation and synthesis. To connect, you run the MCP server via Python and configure a client to point at the server, supplying environment variables for notes location and database path.

Prerequisites:\n- Python and a virtual environment tool (venv or uv)\n- Git\n- Internet access to install dependencies\n\nStep-by-step:\n1) Clone the repository:\n git clone https://github.com/entanglr/zettelkasten-mcp.git\n cd zettelkasten-mcp\n\n2) Create and activate a virtual environment (example using uv):\n uv venv\n source .venv/bin/activate # On Windows: .venv\Scripts\activate\n\n3) Install the MCP CLI and dependencies:\n uv add "mcp[cli]"\n uv sync --all-extras\n\n4) Prepare configuration: create a .env file in the project root and populate connection parameters as described in the README (notes directory and database path). You can start with a copy of the example:\n cp .env.example .env\n\n5) Run the server (see usage guidance for exact command in your environment):\n python -m zettelkasten_mcp.main\n\nPrerequisites note: The README indicates the server is intended to be run via uvx with the package name (zettelkasten-mcp). If you prefer a direct Python invocation, you can run: python -m zettelkasten_mcp.main with the appropriate environment variables set.

Tips and common issues:\n- Ensure ZETTELKASTEN_NOTES_DIR points to a writable directory containing your Markdown notes. The ZETTELKASTEN_DATABASE_PATH path will be created if it does not exist.\n- If you edit Markdown files directly, you may need to rebuild the index with zk_rebuild_index to synchronize the SQLite database with the Markdown source.\n- When configuring Claude Desktop, provide absolute paths to the Python executable in the virtual environment and the module entrypoint to ensure proper startup.\n- If you encounter environment variable issues, verify that the .env file is loaded by the process running the MCP server or export the variables in the shell before starting the server.\n- The system uses a dual storage model: Markdown files are the source of truth, and the SQLite index accelerates search and traversal for AI-assisted workflows.