koei-kaji/zk-mcp
If you are the rightful owner of zk-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.
zk-mcp is an MCP server designed to integrate notes managed by zk with LLMs, facilitating efficient access to knowledge bases.
zk-mcp
zk-mcp is an MCP (Model Context Protocol) server for integrating notes managed by zk with LLMs. It enables LLMs to efficiently access and interact with knowledge bases managed under zk.
Features
- Note Query: Search notes by content, tags, and complex filters
- Link Analysis: Discover relationships between notes (links to, linked by, related)
- Tag Management: List and filter by available tags
- Note Access: Read complete note contents
- Note Creation: Create new notes programmatically
Prerequisites
- zk : a plain text note-taking assistant
- uv
- Any MCP client (e.g., Claude Desktop, Continue, etc.)
Installation
- Clone this repository:
git clone https://github.com/koei-kaji/zk-mcp.git
cd zk-mcp
- Install dependencies:
uv sync
Configuration
Add the following settings to your MCP client's servers.json:
{
"mcpServers": {
"zk": {
"alwaysAllow": [
"get_note",
"get_note_paths",
"get_linking_notes",
"get_tags",
"create_note"
],
"args": [
"--directory",
"/path/to/zk-mcp/",
"run",
"server.py"
],
"command": "uv",
"env": {
"ZK_DIR": "/path/to/your/zk-note-directory/"
}
}
}
}
Important: Replace /path/to/zk-mcp/ with the actual path to this repository and /path/to/your/zk-note-directory/ with the path to your zk notes directory.
Available MCP Tools
This server provides the following MCP tools:
get_note_paths
Search for notes based on various criteria:
- include_str: Filter notes containing specific strings in content or filename
- include_str_operand: Logical operator (
AND/OR) for multiple string filters - exclude_str: Exclude notes containing specific strings
- include_tags: Filter notes by tags
- include_tags_operand: Logical operator (
AND/OR) for multiple tag filters - exclude_tags: Exclude notes with specific tags
get_linking_notes
Discover note relationships:
- link_to_notes: Notes that the specified note links to
- linked_by_notes: Notes that link to the specified note
- related_notes: Notes that are related to the specified note
get_tags
List all available tags in the note repository.
get_note
Read the complete content of a specific note by path.
create_note
Create a new note with the specified title in an optional directory.
Development
Commands
make run- Run the MCP server in development mode withZK_DIR=.make format- Format code using ruff (imports + formatting)make lint- Run linting with ruff and type checking with mypymake test- Run all tests with pytestmake pre-commit- Run both format and lint (recommended before commits)
Package Management
uv add <package>- Add runtime dependencyuv add --dev <package>- Add development dependencyuv run <command>- Run command in virtual environment
Architecture
The server is built using:
- FastMCP: MCP server implementation
- Pydantic: Data validation and serialization
- zk CLI: Backend integration with zk note system
All tools return JSON responses using Pydantic models for type safety and validation.
License
This project is licensed under the MIT License - see the LICENSE file for details.
