# zk-mcp
zk-mcp is an MCP (Model Context Protocol) server for integrating notes managed by [zk](https://zk-org.github.io/zk/index.html) 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](https://zk-org.github.io/zk/index.html)
- [uv](https://docs.astral.sh/uv/)
- Any MCP client (e.g., Claude Desktop, Continue, etc.)
## Installation
1. Clone this repository:
```bash
git clone https://github.com/koei-kaji/zk-mcp.git
cd zk-mcp
```
2. Install dependencies:
```bash
uv sync
```
## Configuration
Add the following settings to your MCP client's `servers.json`:
```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 with `ZK_DIR=.`
- `make format` - Format code using ruff (imports + formatting)
- `make lint` - Run linting with ruff and type checking with mypy
- `make test` - Run all tests with pytest
- `make pre-commit` - Run both format and lint (recommended before commits)
### Package Management
- `uv add <package>` - Add runtime dependency
- `uv add --dev <package>` - Add development dependency
- `uv 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.
