tuskledger-mcp

Сервер протокола контекста модели (MCP) для Tusk Ledger. Предоставляет вашему ИИ-ассистенту типизированный доступ к вашим локальным данным о личных финансах — без передачи чего-либо за пределы вашего компьютера.

Что это такое

Небольшой пакет Python, который работает как локальный сервер Model Context Protocol на вашем ноутбуке. После того как вы добавите его в конфигурацию вашего ИИ-клиента (Claude Desktop, Cursor, Cowork, Claude Code, любой клиент с поддержкой MCP), ваш ассистент сможет вызывать такие инструменты, как:

• list_accounts — все подключенные счета с балансом и статусом синхронизации

• query_transactions — фильтрация по дате, счету, категории и т. д.

• search_transactions — нечеткий текстовый поиск по продавцам и заметкам

• get_spending_summary — итоговые суммы по категориям за выбранный период

• get_top_merchants — кому вы платите больше всего

• get_recurring_subscriptions — Netflix, спортзал и т. д.

• get_upcoming_bills — счета на следующие 30 дней с учетом текущего баланса

• get_net_worth — текущее состояние и тренд за 12 месяцев

• get_holdings — все инвестиционные позиции

• get_investments_summary — сводка портфеля и распределение активов

• get_retirement_projection — сводка по методу Монте-Карло для вашего сохраненного сценария

• run_sync — запуск синхронизации Plaid

• list_stale_accounts — счета с устаревшими данными

Сервер взаимодействует с вашим локальным бэкендом Tusk Ledger по адресу http://127.0.0.1:8000. Никакие данные не передаются через интернет. «Облака MCP» не существует — всё это один процесс Python, работающий на вашем компьютере и общающийся с другим процессом Python на той же машине.

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

Tusk Ledger создан для пользователя, работающего с агентами — того, кто может попросить Claude / Cursor / Cowork сделать то, что пять лет назад было невозможно сделать в одиночку. MCP-сервер — это максимально эффективный шаг к этой цели: ваш ассистент получает типизированный, структурированный доступ к вашим финансовым данным вместо того, чтобы пытаться парсить React UI или угадывать схему базы данных.

Примеры использования после установки:

• «Классифицируй транзакции из Whole Foods за последние 6 месяцев как "Продукты" вместо "Покупки".» → Ассистент запрашивает их, вы подтверждаете, затем он создает правило.

• «Сколько я потратил на кофе в прошлом квартале?» → 3 секунды, никаких кликов по интерфейсу.

• «Мой чистый капитал упал сегодня утром — в чем причина?» → Ассистент получает данные о счетах, балансах и недавних транзакциях и проводит диагностику.

• «Успеваю ли я внести максимум на свой HSA в этом году?» → Читает остаток HSA + взносы с начала года + лимит IRS, возвращает разницу.

Предварительные требования

• Запущенная установка Tusk Ledger (основное приложение)

• Python 3.10+

• Клиент с поддержкой MCP (Claude Desktop, Cursor, Cowork, Claude Code, …)

Установка

Вариант А — uvx (рекомендуется; без постоянной установки)

Если у вас есть uv (pip install uv):

// In your MCP client's config
{
  "mcpServers": {
    "tuskledger": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/BradMorphsters/tuskledger-mcp", "tuskledger-mcp"]
    }
  }
}

uvx управляет изолированным окружением Python; ничего не засоряет ваш глобальный Python. Сервер загружается и кэшируется при первом вызове.

Вариант Б — pip install из GitHub

pip install git+https://github.com/BradMorphsters/tuskledger-mcp

Затем укажите вашему MCP-клиенту путь к установленному бинарному файлу tuskledger-mcp:

{
  "mcpServers": {
    "tuskledger": {
      "command": "tuskledger-mcp"
    }
  }
}

(Используйте полный путь из which tuskledger-mcp, если вы используете venv.)

Вариант В — клонирование для разработки

git clone https://github.com/BradMorphsters/tuskledger-mcp
cd tuskledger-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .

Где находятся конфигурации MCP-клиентов

После редактирования конфигурации перезапустите клиент. Сервер запускается при старте клиента и завершает работу при его закрытии.

Конфигурация

Две переменные окружения, обе необязательны:

Пример:

{
  "mcpServers": {
    "tuskledger": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/BradMorphsters/tuskledger-mcp", "tuskledger-mcp"],
      "env": {
        "TUSKLEDGER_BASE_URL": "http://127.0.0.1:8000",
        "TUSKLEDGER_TIMEOUT_SECONDS": "30"
      }
    }
  }
}

Аутентификация

Эта версия v0 предполагает, что ваш бэкенд Tusk Ledger запущен с DEV_BYPASS_AUTH=true (стандартный паттерн для одной машины, описанный в README основного репозитория). Если вы оставили аутентификацию включенной, вызовы MCP-сервера будут завершаться ошибкой 401, и вы увидите ошибку в ответе ассистента.

Поддержка аутентификации находится в планах. До тех пор, если вам нужны и аутентификация, и MCP, запускайте бэкенд с DEV_BYPASS_AUTH=true только когда вы используете ассистента, и возвращайте настройки обратно, когда закончите.

Что этот сервер намеренно НЕ делает

По дизайну, v0 работает преимущественно на чтение. Сервер не предоставляет возможности:

• Удалять счета, транзакции, правила или цели

• Изменять схему базы данных или выполнять миграции

• Отключать аутентификацию или менять ключ шифрования

• Трогать токены доступа Plaid

• Отправлять данные куда-либо за пределы 127.0.0.1

Обоснование: ИИ-ассистент должен помогать вам понимать ваши данные и выполнять безопасные операции (синхронизация, запросы), но необратимые изменения должны происходить в веб-интерфейсе, где вы видите, что именно собираетесь сделать. Мы можем добавить структурированные инструменты записи (например, «создать правило») в будущих версиях с явными потоками подтверждения, но планка безопасности останется высокой.

Устранение неполадок

Could not reach Tusk Ledger backend at http://127.0.0.1:8000 — Ваше приложение Tusk Ledger не запущено. Из основного репозитория: ./start.sh.

401 Unauthorized от любого инструмента — Аутентификация включена. См. раздел «Аутентификация» выше. Пока запускайте с DEV_BYPASS_AUTH=true.

404 Not Found — Бэкенд не имеет эндпоинта, к которому мы пытаемся обратиться. Вероятно, вы используете старую версию Tusk Ledger. Обновите основное приложение, перезапустите MCP-клиент.

Инструменты не появляются в ассистенте — MCP-сервер не смог запуститься. Проверьте логи MCP-сервера вашего клиента (в Claude Desktop есть пункт меню «View MCP server logs»). Распространенные причины: неверный путь в конфигурации, Python отсутствует в PATH, uvx не установлен.

Общая проверка работоспособности — Из основного репозитория Tusk Ledger: ./tuskledger doctor. Это каноническая диагностика для всей установки.

Разработка

git clone https://github.com/BradMorphsters/tuskledger-mcp
cd tuskledger-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .
pip install pytest pytest-asyncio
pytest tests/ -v

Тесты не поднимают транспорт MCP — они напрямую проверяют уровень диспетчеризации с помощью фиктивного клиента. Сам протокол MCP — это просто обертка.

CI запускает тот же набор тестов на Python 3.10/3.11/3.12 через GitHub Actions (см. .github/workflows/ci.yml).

Ссылки на проект

• Основное приложение: https://github.com/BradMorphsters/tuskledger

• Сайт проекта: https://www.tuskledger.com

• Для агентов, сканирующих внешние ресурсы: https://www.tuskledger.com/llms.txt

• Проблемы / обсуждения: https://github.com/BradMorphsters/tuskledger-mcp/issues

• Лицензия: MIT