Yandex Wiki MCP

Реализация MCP-сервера для Яндекс Вики с режимами read/write и readonly.

Содержимое

• mcp-yandex-wiki — полный режим (чтение + создание/обновление/append)
• mcp-yandex-wiki-ro — read-only режим (только чтение)

Установка

1. Установить uv (если ещё не установлен).
2. Получить OAuth-токен Яндекс и org_id:
   1. Создать приложение на oauth.yandex.ru с правами Wiki.
   2. Подставить client_id в URL:

      https://oauth.yandex.ru/authorize?response_type=token&client_id=<CLIENT_ID>
      

      и авторизоваться.

Переменные окружения

Обязательные:

• WIKI_TOKEN или TRACKER_TOKEN
• WIKI_ORG_ID или TRACKER_ORG_ID

Опциональные:

• WIKI_API_BASE_URL (по умолчанию https://api.wiki.yandex.net/v1)
• TRANSPORT (stdio по умолчанию)
• HOST (127.0.0.1)
• PORT (8088)
• MCP_PATH (/mcp)
• TOOLS_CACHE_ENABLED (true/false, по умолчанию false)
• TOOLS_CACHE_REDIS_TTL (в секундах, по умолчанию 3600)
• REDIS_ENDPOINT (localhost)
• REDIS_PORT (6379)
• REDIS_DB (0)
• REDIS_PASSWORD
• REDIS_POOL_MAX_SIZE (10)
• READONLY (true/false)

Кэширование (Redis)

Кэшируются только read-операции для Wiki:

• wiki_page_get
• wiki_page_get_by_url
• wiki_page_get_text_by_url

Особенности:

• включается через TOOLS_CACHE_ENABLED=true
• кэш живёт в Redis (REDIS_*)
• при любых write-операциях (create, update, append_content) кэш инвалидируется для затронутых страниц/slug
• в ответах добавляется флаг _mcp_cache_hit (true/false)

Минимальный пример для локального Redis:

docker run -p 6379:6379 --name redis-cache -d redis:alpine

TRACKER_TOKEN=your_token TRACKER_ORG_ID=your_org_id \
  TOOLS_CACHE_ENABLED=true REDIS_ENDPOINT=127.0.0.1 REDIS_PORT=6379 uvx mcp-yandex-wiki

Production-подобный пример:

TRACKER_TOKEN=your_token TRACKER_ORG_ID=your_org_id \
TOOLS_CACHE_ENABLED=true \
  REDIS_ENDPOINT=redis.internal \
  REDIS_PORT=6379 \
  REDIS_DB=0 \
  REDIS_PASSWORD=secret \
  TOOLS_CACHE_REDIS_TTL=7200 \
  uvx mcp-yandex-wiki

Быстрый запуск (через PyPI)

TRACKER_TOKEN=your_token TRACKER_ORG_ID=your_org_id \
  uvx mcp-yandex-wiki

TRACKER_TOKEN=your_token TRACKER_ORG_ID=your_org_id \
  uvx --from mcp-yandex-wiki mcp-yandex-wiki-ro

Альтернатива (после установки):

pip install mcp-yandex-wiki
python -m yandex_wiki_mcp

Подключение в MCP-агентах (через PyPI)

Claude Code

Требования: должен быть установлен uvx (входит в uv).

claude mcp add yandex-wiki \
  -e WIKI_TOKEN=your_token \
  -e WIKI_ORG_ID=your_org_id \
  -- uvx mcp-yandex-wiki

claude mcp add yandex-wiki-ro \
  -e WIKI_TOKEN=your_token \
  -e WIKI_ORG_ID=your_org_id \
  -- uvx --from mcp-yandex-wiki mcp-yandex-wiki-ro --readonly

Если используете TRACKER_*-переменные, замените их на:

claude mcp add yandex-wiki \
  -e TRACKER_TOKEN=your_token \
  -e TRACKER_ORG_ID=your_org_id \
  -- uvx mcp-yandex-wiki

Codex (конфиг проекта)

[mcp_servers.yandex-wiki]
command = "uvx"
args = ["mcp-yandex-wiki"]
env = { WIKI_TOKEN = "your_token", WIKI_ORG_ID = "your_org_id" }

[mcp_servers.yandex-wiki-ro]
command = "uvx"
args = ["--from", "mcp-yandex-wiki", "mcp-yandex-wiki-ro"]
env = { WIKI_TOKEN = "your_token", WIKI_ORG_ID = "your_org_id" }

Cursor

1. Открыть Settings → Cursor Settings → MCP → + Add new global MCP server. Откроется файл ~/.cursor/mcp.json.
2. Добавить конфигурацию:

{
  "mcpServers": {
    "yandex-wiki": {
      "command": "uvx",
      "args": ["mcp-yandex-wiki"],
      "env": {
        "WIKI_TOKEN": "your_token",
        "WIKI_ORG_ID": "your_org_id"
      }
    }
  }
}

Для read-only режима:

{
  "mcpServers": {
    "yandex-wiki-ro": {
      "command": "uvx",
      "args": ["--from", "mcp-yandex-wiki", "mcp-yandex-wiki-ro"],
      "env": {
        "WIKI_TOKEN": "your_token",
        "WIKI_ORG_ID": "your_org_id"
      }
    }
  }
}

Можно также добавить на уровне проекта — создайте файл .cursor/mcp.json в корне репозитория с аналогичным содержимым.

3. Вернуться в Settings → MCP и убедиться, что у сервера зелёный индикатор (статус «running»).

Другие MCP-клиенты (JSON, общий шаблон)

{
  "mcpServers": {
    "yandex-wiki": {
      "command": "uvx",
      "args": ["mcp-yandex-wiki"],
      "env": {
        "WIKI_TOKEN": "your_token",
        "WIKI_ORG_ID": "your_org_id"
      }
    },
    "yandex-wiki-ro": {
      "command": "uvx",
      "args": ["--from", "mcp-yandex-wiki", "mcp-yandex-wiki-ro"],
      "env": {
        "WIKI_TOKEN": "your_token",
        "WIKI_ORG_ID": "your_org_id"
      }
    }
  }
}

Инструменты

mcp-yandex-wiki (rw)

• wiki_page_get
• wiki_page_get_by_url
• wiki_page_get_text_by_url
• wiki_page_create
• wiki_page_update
• wiki_page_append_content

mcp-yandex-wiki-ro

• wiki_page_get
• wiki_page_get_by_url
• wiki_page_get_text_by_url
• write-инструменты возвращают 403

Отладка (MCP Inspector)

Для интерактивной отладки MCP-сервера можно использовать MCP Inspector.

1. Запустить сервер в режиме SSE:

uv run fastmcp run yandex_wiki_mcp/server.py --transport sse

2. В другом терминале запустить Inspector:

npx @modelcontextprotocol/inspector@latest

3. В открывшемся интерфейсе Inspector выбрать Transport Type: SSE и указать URL:

http://localhost:8000/sse

4. Нажать Connect — Inspector подключится к серверу и покажет список доступных инструментов, позволяя вызывать их вручную и видеть ответы.

Настройки FastMCP для production

Сервер поддерживает переменные окружения FastMCP для тонкой настройки поведения:

• FASTMCP_MASK_ERROR_DETAILS — при true маскирует детали ошибок в ответах клиентам. Показываются только сообщения из явно выброшенных ToolError. Рекомендуется для production.
• FASTMCP_STRICT_INPUT_VALIDATION — при true включает строгую валидацию входных данных инструментов по JSON-схемам. При false (по умолчанию) допускаются совместимые преобразования типов (например, строка "10" → число 10).