mcp-zettel

Предоставьте Claude (или любому MCP-клиенту) постоянную память в виде Zettelkasten.

MCP-сервер, который открывает личную базу знаний из атомарных, взаимосвязанных markdown-заметок для Claude Desktop, Claude Code, Cursor или любого другого MCP-совместимого клиента. Подключите его, и помощник сможет создавать заметки, перекрестно ссылаться на них с помощью [[wiki-links]], искать по ключевым словам или тегам, а также просматривать обратные ссылки — это позволит ему создавать и использовать долговечный контекст в разных сессиях без необходимости что-либо копировать вручную.

Зачем это нужно

Каждый чат, который вы начинаете с LLM, начинается с нулевого контекста о том, что вы уже решили, написали или узнали. Метод Zettelkasten (небольшие атомарные заметки + явные ссылки между ними) отлично подходит для памяти, доступной LLM: фрагменты естественным образом малы, ссылки делают релевантность явной, а хранилище представляет собой обычные markdown-файлы на вашем диске.

Этот MCP-сервер предоставляет эту базу знаний любому LLM-клиенту через инструменты MCP, чтобы модель могла:

• Создавать новую заметку, когда вы делитесь решением или инсайтом, который стоит сохранить

• Искать заметки по теме перед ответом («что я решил по поводу X?»)

• Связывать заметки двусторонними ссылками для построения графа («это противоречит [[a3f2c9]]»)

• Просматривать обратные ссылки, чтобы найти все, что связано с концепцией

Вы храните обычные markdown-файлы на диске. Модель получает структурированный доступ к ним.

Related MCP server: obsidian-pkm

Как это выглядит в клиенте

После подключения сервера LLM может делать следующее (ваш клиент покажет фактические вызовы инструментов):

> What did I conclude about RAG chunk sizes?
[searches notes with query "rag chunk size"]
[reads 2 matching notes]
Based on your notes a3f2c9 ("RAG chunk sizing") and b7e412 ("Sentence-boundary
splitting"), you concluded: 800 chars with ~15% overlap, sentence-aligned.
You flagged that pure character chunking ([[2f00a1]]) hurt recall on your
arxiv set and moved away from it.

Предоставленные инструменты MCP

Плюс ресурсы MCP:

• zettel://all — однострочный индекс всех заметок

• zettel://{note_id} — полностью отрендеренная заметка

• zettel://graph — v0.4. Mermaid-диаграмма всех заметок + [[wiki-link]] в хранилище, отрендеренная встроенно любым клиентом с поддержкой markdown+mermaid (Claude Desktop, Obsidian, mdBook…).

• zettel://graph/tag/{tag} — v0.4. Та же диаграмма, но ограниченная заметками с тегом {tag} плюс их прямыми соседями — полезно, когда полный граф становится слишком шумным для чтения.

Два инструмента поиска, а не один

Поиск по ключевым словам — это то, что вам нужно, когда вы знаете термин. Он дешевый, ранжирование предсказуемо, а точные совпадения всегда выигрывают у похожих по звучанию. Семантический поиск выигрывает, когда формулировка запроса не совпадает с формулировкой заметки — например, запрос «ограничение скорости» (rate limiting), когда в заметке это называется «дросселирование» (throttling), или «почему мой кэш холодный», когда заметка о «настройке TTL». LLM может вызвать тот инструмент, который имеет смысл; описания инструментов подсказывают ей, какой выбрать.

Модель эмбеддингов по умолчанию — BAAI/bge-small-en-v1.5 (384-размерная, ~130 МБ, только CPU). Переопределите с помощью MCP_ZETTEL_EMBEDDING_MODEL. Индекс перестраивается лениво при первом семантическом запросе после любой записи, поэтому в первый раз будет небольшая задержка — после этого он остается в памяти на все время работы процесса сервера.

Установка

git clone https://github.com/dhruvpatel1706/mcp-zettel.git
cd mcp-zettel
pip install -e .

Python 3.10+.

Настройка

Claude Desktop

Отредактируйте ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) или эквивалентный файл в вашей ОС и добавьте:

{
  "mcpServers": {
    "zettel": {
      "command": "mcp-zettel-server"
    }
  }
}

Перезапустите Claude Desktop. Инструменты zettel теперь доступны модели.

Claude Code

claude mcp add zettel -- mcp-zettel-server

Cursor / Continue / любой stdio MCP-клиент

Укажите клиенту mcp-zettel-server в качестве команды; сервер общается по MCP через stdio.

Пользовательское расположение хранилища

Установите MCP_ZETTEL_ROOT для переопределения пути по умолчанию ~/.mcp-zettel:

{
  "mcpServers": {
    "zettel": {
      "command": "mcp-zettel-server",
      "env": { "MCP_ZETTEL_ROOT": "/Users/you/vault" }
    }
  }
}

Использование CLI напрямую (MCP-клиент не требуется)

То же хранилище доступно через обычный CLI — полезно для опытных пользователей, которые хотят просматривать, редактировать или наполнять базу знаний вне сессии LLM.

mcp-zettel create "RAG chunk sizing" \
  --body "Settled on 800 chars, 15% overlap, sentence-aligned. See [[b7e412]]." \
  --tag rag --tag decisions

mcp-zettel list --tag rag
mcp-zettel search "sentence boundary"
mcp-zettel show a3f2c9
mcp-zettel backlinks a3f2c9

Структура на диске

~/.mcp-zettel/
└── notes/
    ├── a3f2c9.md          ← one markdown file per note
    ├── b7e412.md          ← YAML frontmatter: title, tags, created_at, updated_at
    └── ...                ← body is plain markdown; [[id]] is a wiki-link

Каждая заметка — это отдельный файл. Это означает: легкое резервное копирование (git), легкий grep, отсутствие привязки к поставщику. Если вы когда-нибудь перестанете использовать этот сервер, у вас останется директория с markdown-файлами.

Проектные решения

• Файлы, а не база данных. Одна заметка на markdown-файл означает, что вы можете редактировать их в любом редакторе, делать резервные копии с помощью git и просматривать без специальных инструментов. Хранилище — это тонкая прослойка поверх.

• Короткие hex-ID, а не заголовки-слаги. [[a3f2c9]] стабилен — переименуйте заголовок, и все входящие ссылки все равно будут работать. Также короче, чем слаг на основе имени файла.

• Двусторонние ссылки вычисляются, а не хранятся. Обратные ссылки вычисляются при чтении путем сканирования тела каждой заметки на наличие [[target_id]]. Нет отдельного индекса, который нужно поддерживать в актуальном состоянии. Это тривиально при масштабе, для которого это спроектировано (≤ несколько тысяч заметок).

• Поиск с учетом веса заголовка/тега. Совпадения в заголовке считаются за 3×, в тегах — за 2×, в теле — за 1×. Это соответствует интуиции: если в заголовке заметки упоминается «поиск», она больше относится к поиску, чем заметка, где это слово встречается один раз в середине текста.

• FastMCP, а не низкоуровневый MCP. Поверхность FastMCP Python SDK для MCP означает, что инструменты — это просто функции Python с аргументами, типизированными через Pydantic — никакого ручного написания JSON Schema.

Разработка

pip install -e ".[dev]"
pytest
black --check src tests
isort --check-only --profile black src tests
flake8 src tests --max-line-length=100 --ignore=E501,W503,E203

CI запускается на Python 3.10 / 3.11 / 3.12.

Проверяйте сервер интерактивно с помощью инспектора MCP:

npx @modelcontextprotocol/inspector mcp-zettel-server

Шаблоны промптов (v0.3)

MCP-клиенты, поддерживающие меню промптов (Claude Desktop, Cursor), получают четыре серверных шаблона, которые кодируют «правильный способ» выполнения обычных действий Zettelkasten, чтобы вам не приходилось перепечатывать инструкции:

Это просто функции, возвращающие строки, зарегистрированные через @mcp.prompt(). Хранение формулировок на стороне сервера означает, что один и тот же промпт «distill» ведет себя одинаково, вызываете ли вы его из Claude Desktop, Claude Code или Cursor.

Дорожная карта

• [x] v0.2 — семантический поиск на основе эмбеддингов вместе с поиском по ключевым словам

• [x] v0.3 — шаблоны @mcp.prompt() для обычных операций с заметками

• [x] v0.4 — ресурс графового представления (zettel://graph), возвращающий mermaid-диаграмму ссылок

• [ ] v0.5 — удаленный Streamable HTTP-транспорт для доступа с нескольких устройств

Лицензия

MIT. См. LICENSE.