Metadata-Version: 2.4
Name: zenmoney-mcp
Version: 0.1.0
Summary: MCP server for ZenMoney personal finance tracking
Project-URL: Repository, https://github.com/Romandredan/zenmoney-mcp
Project-URL: Issues, https://github.com/Romandredan/zenmoney-mcp/issues
Author: Roman Danilov
License-Expression: MIT
License-File: LICENSE
Keywords: finance,mcp,model-context-protocol,zenmoney
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.12
Requires-Dist: authlib>=1.3
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.9
Requires-Dist: pydantic>=2.7
Description-Content-Type: text/markdown

# zenmoney-mcp

MCP-сервер для [ZenMoney](https://zenmoney.ru/) — сервиса учёта личных финансов.
Позволяет ИИ-ассистенту (Claude Desktop, Claude Code, Kimi Code и др.)
вносить транзакции, смотреть счета, категории и бюджеты, а также строить
аналитику по расходам и доходам.

Кратко о возможностях: транзакции (просмотр, добавление, редактирование,
удаление, переводы), автокатегоризация (свои локальные правила + suggest
ZenMoney), справочники, бюджеты с фактом исполнения, аналитика в валюте
пользователя, локальный кэш с инкрементальной синхронизацией.

## Документация

- [docs/tools.md](docs/tools.md) — все инструменты MCP: параметры, форматы, примеры;
- [docs/cli.md](docs/cli.md) — CLI-команды, переменные окружения, файлы данных;
- [docs/rules.md](docs/rules.md) — правила категоризации;
- [docs/scenarios.md](docs/scenarios.md) — сценарии использования с ассистентом.

## Быстрый старт

Понадобится установленный [uv](https://docs.astral.sh/uv/) (Python ставить
не нужно — `uv` скачает его сам). Дальше два шага:

1. Получите токен на [zerro.app/token](https://zerro.app/token) —
   авторизуйтесь через ZenMoney и скопируйте токен (способ из
   [официальной wiki ZenMoney API](https://github.com/zenmoney/ZenPlugins/wiki/ZenMoney-API)).
2. Добавьте блок в конфиг своего MCP-клиента:

```json
{
  "mcpServers": {
    "zenmoney": {
      "command": "uvx",
      "args": ["zenmoney-mcp"],
      "env": { "ZENMONEY_TOKEN": "<токен>" }
    }
  }
}
```

Куда вставлять (JSON-блок везде одинаковый):

- **Claude Desktop** — `claude_desktop_config.json` (Settings → Developer →
  Edit Config);
- **Claude Code** — `.mcp.json` в корне проекта или
  `claude mcp add zenmoney -e ZENMONEY_TOKEN=<токен> -- uvx zenmoney-mcp`;
- **Kimi Code** — `mcp.json`.

После перезапуска клиента у ассистента появится 21 инструмент zenmoney.
`uvx` сам скачает пакет с PyPI при первом запуске.

## Безопасность

- Токен в конфиге MCP-клиента хранится **открытым текстом**. Не коммитьте
  проектный `.mcp.json` с токеном в git — добавьте его в `.gitignore` или
  держите токен только в пользовательском (не проектном) конфиге.
- Вставляйте токен в конфиг руками, а не через ассистента: сервер устроен
  так, что токен читается с диска или из окружения и **не проходит через
  ИИ-модель** — модель видит только названия инструментов и их аргументы.
  Не присылайте токен в переписку.
- Если не хотите держать токен в конфиге вовсе — сохраните его в файл
  командой `set-token` (см. ниже), конфиг останется чистым.

## Альтернативные способы авторизации

- **Токен в файле**: `uvx zenmoney-mcp set-token` — токен запрашивается
  интерактивно (не попадёт в историю shell) и сохраняется в `token.json`;
  блок `env` из конфига тогда не нужен.
- **Своё OAuth-приложение** (даёт авто-refresh токена):
  зарегистрируйте приложение у ZenMoney и выполните `uvx zenmoney-mcp auth`.

Детали обеих команд, переменные окружения и расположение файлов —
в [docs/cli.md](docs/cli.md).

## Возможности и инструменты

- Синхронизация и справочники: `sync`, `get_accounts`, `get_tags`,
  `get_merchants`, `get_instruments`.
- Транзакции: `get_transactions`, `add_transaction`, `update_transaction`,
  `delete_transaction`, `suggest_transaction`.
- Правила категоризации: `add_rule`, `list_rules`, `delete_rule`,
  `test_rules`, `reclassify`.
- Бюджеты: `get_budgets`, `set_budget`.
- Аналитика: `spending_by_category`, `income_vs_expense`,
  `account_balances`, `monthly_summary`.

Полный справочник с параметрами и примерами — [docs/tools.md](docs/tools.md).

## Разработка

```bash
git clone https://github.com/Romandredan/zenmoney-mcp
cd zenmoney-mcp
uv sync          # установить зависимости
uv run pytest -q # тесты (без сети, API замокан)
```

Запуск локальной версии сервера — `uv run zenmoney-mcp`; чтобы MCP-клиент
использовал исходники вместо пакета с PyPI:

```json
{
  "mcpServers": {
    "zenmoney": {
      "command": "uv",
      "args": ["run", "--directory", "<путь к репозиторию>", "zenmoney-mcp"],
      "env": { "ZENMONEY_TOKEN": "<токен>" }
    }
  }
}
```

В `src/zenmoney_mcp/zenmoney/` завендорен клиент
[sakost/zenmoney-api](https://github.com/sakost/zenmoney-api) (MIT,
см. `NOTICE.md` в том же каталоге).
