Перейти к основному содержимому

chk-mcp — установка и регистрация в Claude MCP

Версия документа: 1.0 Версия инструмента: 0.2.1 Дата: 29.04.2026 Статус: Готов к обсуждению

Назначение документа​

Документ описывает пошаговую установку MCP-сервера chk-mcp и его регистрацию в конфигурации MCP-клиента (Claude Code, Codex, любой другой). После прохождения шагов агент в новой сессии увидит инструменты mcp__chk-mcp__chk_* и сможет работать с трекером analytics.vitrip.store напрямую.

Системные требования​

  • Python 3.11 или выше (проверка: python3 --version).
  • Доступ в Интернет к https://analytics.vitrip.store.
  • Токен External API с нужными scope (см. ниже).
  • Linux/WSL/macOS. На Windows нативно не тестировался, рекомендуется WSL.

Получение токена​

Описано подробно в External API v1 — полное руководство, раздел «Как получить токен». Кратко:

  1. Войти в analytics.vitrip.store под обычным аккаунтом.
  2. Открыть Профиль → блок External API токени.
  3. Создать новый токен с понятным именем (рекомендуется: Claude integration, Codex agent, MCP integration — что-то узнаваемое).
  4. Срок действия — на усмотрение, рекомендуется month-90 days с возможностью продления.
  5. Scope — рекомендуется выдавать минимально необходимый. Для полноценной работы агента: все 9 scope (auth:me, projects:read, projects:search, items:read, items:status.write, items:planning.write, comments:write, answers:write, items:materials.write). Для read-only режима (агент только читает, не пишет): первые 4.
  6. Сохранить raw token — длинная строка вида chk_xxxxxxxxxxxxxxxxxxxxx. Показывается один раз.

Установка пакета​

Шаг 1. Клонировать или открыть директорию проекта​

Код живёт в /mnt/d/SITES/chk-mcp/. Если директории ещё нет — её надо создать (см. README.md в корне проекта).

Шаг 2. Создать виртуальное окружение​

cd /mnt/d/SITES/chk-mcp
python3 -m venv .venv

Шаг 3. Установить пакет в editable-режиме​

.venv/bin/pip install -e .

Editable-режим (-e) означает, что изменения в коде сразу видны без переустановки.

Шаг 4. Smoke-test без MCP​

Проверить, что клиент работает с production API:

CHK_TOKEN='chk_xxxxxxxxxxxxxxxxxxxxxxxxxxx' .venv/bin/python -c "
import asyncio
from chk_mcp.client import ChkClient
from chk_mcp.config import load

async def main():
    async with ChkClient(load()) as c:
        me = await c.auth_me()
        print(f'Connected as: {me[\"user\"][\"name\"]}')
        print(f'Scopes: {me[\"token\"][\"scopes\"]}')

asyncio.run(main())
"

Ожидаемый вывод: имя пользователя и список scope. Если получаешь TokenError — токен неверный или истёк.

Конфигурация — два способа​

Сервер ищет токен и base URL в таком порядке: переменные окружения → файл ~/.config/chk-mcp/config.toml → дефолт base URL.

Способ A. Переменные окружения​

export CHK_TOKEN='chk_xxxxxxxxxxxxxxxxxxxxxxxxxxx'
export CHK_BASE_URL='https://analytics.vitrip.store/api/external/v1/'  # необязательно, дефолт

Удобно для одноразового запуска. Не сохраняется между сессиями.

Способ B. Файл конфигурации​

Создать ~/.config/chk-mcp/config.toml:

token = "chk_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
base_url = "https://analytics.vitrip.store/api/external/v1/"

Подходит для постоянного использования — не нужно каждый раз экспортировать.

Важно. Файл содержит секрет — выставить корректные права:

chmod 600 ~/.config/chk-mcp/config.toml

Регистрация в Claude MCP​

Точное место конфигурационного файла зависит от среды:

  • Claude Code (CLI): ~/.claude/mcp_servers.json или конфиг в текущем проекте .claude/mcp_servers.json (зависит от установки).
  • Claude Desktop: ~/.config/Claude/claude_desktop_config.json (Linux) / ~/Library/Application Support/Claude/claude_desktop_config.json (macOS).
  • Codex / Кастомный MCP-клиент: см. документацию клиента.

Каноничный блок регистрации (рекомендуется)​

Токен лежит в ~/.config/chk-mcp/config.toml с правами chmod 600. В блоке регистрации MCP его не дублируем — это безопаснее (Claude config не содержит секретов и его можно копировать/синхронизировать без рисков):

{
  "mcpServers": {
    "chk-mcp": {
      "command": "/mnt/d/SITES/chk-mcp/.venv/bin/python",
      "args": ["-m", "chk_mcp"],
      "env": {}
    }
  }
}

Что важно:

  • command — абсолютный путь к Python из virtualenv проекта. Не системный python — там не будет установленных зависимостей.
  • args — ["-m", "chk_mcp"] — запуск пакета как модуля.
  • env — пустой; токен подгружается из ~/.config/chk-mcp/config.toml через chk_mcp.config.load() (см. главу «Конфигурация»).
  • Имя chk-mcp — это namespace для tools. После рестарта клиента инструменты появятся с префиксом mcp__chk-mcp__chk_*.

Альтернативный блок с токеном в env (не рекомендуется)​

Если по какой-то причине нужно положить токен прямо в Claude config (например, для одноразового тестирования без создания файла конфигурации):

{
  "mcpServers": {
    "chk-mcp": {
      "command": "/mnt/d/SITES/chk-mcp/.venv/bin/python",
      "args": ["-m", "chk_mcp"],
      "env": {
        "CHK_TOKEN": "chk_xxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}

Минусы этого подхода:

  • Claude config попадает в ~/.claude.json без специальных прав (обычно 644) — токен видим всем процессам пользователя.
  • При синхронизации Claude config между машинами (или резервном копировании) токен утекает.
  • Backup-файлы Claude config также содержат токен.

Если используешь этот подход — обязательно chmod 600 ~/.claude.json и удаляй backup-файлы вручную.

Активация​

После правки конфига перезапустить MCP-клиент (Claude Code: новая сессия; Claude Desktop: «Restart Claude»). При старте клиент:

  1. Прочитает конфиг, найдёт chk-mcp в mcpServers.
  2. Запустит подпроцесс python -m chk_mcp со stdio.
  3. Вызовет list_tools() — получит 13 tools.
  4. Покажет их в списке доступных инструментов с префиксом mcp__chk-mcp__chk_*.

Проверка регистрации​

В новой сессии Claude вызвать любой read-only инструмент:

mcp__chk-mcp__chk_auth_me({})

Ожидаемый ответ — JSON с user, token, scopes (как в Шаге 4 раздела «Установка»). Если ответ {error: {code: "token_invalid", ...}} — проблема с токеном. Если tool вообще не виден — проблема с регистрацией: проверить путь к Python, проверить что venv активирован при ручном запуске, посмотреть логи клиента.

Откат​

Удалить блок chk-mcp из mcpServers, перезапустить клиент. Опционально удалить директорию /mnt/d/SITES/chk-mcp/ и файл ~/.config/chk-mcp/config.toml. Сам токен в analytics.vitrip.store нужно отозвать вручную через профиль.

Связанная документация​