personal-finance-mcp

Неофициальный проект. Этот проект не связан, не одобрен и не спонсируется Plaid Inc. "Plaid" является торговой маркой Plaid Inc. Это самохостируемый клиент, который взаимодействует с API Plaid, используя предоставленные вами учетные данные.

Самохостируемый MCP-сервер с доступом только для чтения, который подключает ваши банковские счета, кредитные карты, займы и брокерские счета (через Plaid) к MCP-клиенту, такому как Claude Code. Задавайте вопросы о своих финансах на обычном языке — без участия сторонних агрегаторов (Monarch, Mint и т. д.).

Что можно спросить

• "Какой мой общий баланс по всем счетам?"

• "Покажи транзакции на сумму более $100 за последние 30 дней."

• "За какие подписки я все еще плачу?"

• "Сколько я потратил на продукты в прошлом месяце?"

• "Есть ли банк, требующий повторной аутентификации?"

Пример сессии (иллюстративный):

you    : What did I spend on groceries last month?
claude : [calls get_transactions]
         $487.23 across 14 transactions. Top merchants:
         Whole Foods ($198), Trader Joe's ($156), Safeway ($89).

you    : Any subscriptions I'm still paying for?
claude : [calls get_recurring_transactions]
         7 active recurring outflows totaling $142/mo:
         Netflix ($15.99), Spotify ($11.99), NYT ($4), ...

Related MCP server: plaid-mcp

Инструменты

Все 9 инструментов работают только для чтения. Каждый возвращает {<data>: [...], "warnings": [...]} так, чтобы один неисправный банк не нарушал работу всего запроса.

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

Требуется Python 3.11+, аккаунт Plaid (бесплатный план Trial) и MCP-клиент.

1. Настройка Plaid

1. Зарегистрируйтесь на https://dashboard.plaid.com/signup → выберите план Trial (бесплатно, 10 элементов).

2. Team Settings → Products: включите Transactions, Liabilities, Investments.

3. Team Settings → API: скопируйте ваш client_id и production secret.

2. Установка

git clone https://github.com/JosueM1109/personal-finance-mcp.git
cd personal-finance-mcp
python3.11 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # then fill in PLAID_CLIENT_ID and PLAID_SECRET
pytest -v              # sanity check

3. Подключение каждого банка

Запускайте по одному разу для каждого банка, который хотите подключить:

uvicorn link_helper:app --port 8765

Откройте http://localhost:8765, нажмите Link a bank и завершите процесс Plaid Link. Терминал выведет строку вида PLAID_TOKEN_CHASE=access-prod-xxx... — вставьте ее в .env и повторите для каждого банка.

4. Запуск

python server.py   # serves on http://localhost:8000/mcp

5. Добавление в Claude Code

claude mcp add --transport http personal-finance http://localhost:8000/mcp

Попробуйте "list my accounts", чтобы проверить работу.

Развертывание

Для развертывания, доступного отовсюду:

• Docker (включен): docker build -t personal-finance-mcp . && docker run --rm -p 8000:8000 --env-file .env personal-finance-mcp

• Любой Python-хостинг (Fly.io, Railway, Raspberry Pi + Tailscale, VPS): установите переменные окружения из .env.example, откройте /mcp через HTTPS, защитите авторизацией.

• Prefect Horizon (используется автором — $0 регулярных затрат): см. docs/DEPLOYMENT.md для полного руководства.

Защитите эндпоинт. Открытый MCP-эндпоинт с вашими токенами раскрывает все подключенные счета. Используйте OAuth 2.1, Cloudflare Access или привяжите только к частной сети.

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

• Однопользовательский режим. Одно развертывание на человека. Не делитесь доступом.

• Только чтение. Ни один инструмент не изменяет состояние в финансовых учреждениях. Не добавляйте инструменты, которые это делают.

• Токены живут в переменных окружения, никогда не записываются на диск. .env добавлен в gitignore.

• Вы несете ответственность за соблюдение правил Plaid. Вы являетесь клиентом Plaid под своей учетной записью.

Перед каждым развертыванием:

• [ ] .env никогда не коммитится: git log --all -- .env ничего не возвращает

• [ ] В истории нет реальных токенов: git log -S'access-prod-' --all возвращает только заглушки

• [ ] Перед MCP-эндпоинтом стоит защита (или доступ только через localhost)

• [ ] HORIZON=1 (или аналогичное) установлено в переменных окружения развертывания, блокируя link_helper.py там

• [ ] Проверяйте get_institutions_status() каждые несколько недель на предмет необходимости повторной аутентификации

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

Инструмент возвращает пустоту, несмотря на наличие данных. Продукты Plaid не были включены при подключении банка. Переподключите с активными Transactions + Liabilities + Investments. Инструмент выводит PRODUCTS_NOT_SUPPORTED в warnings, если причина в этом.

get_institutions_status() показывает re_auth_required. Сессия Plaid для банка истекла. Запустите link_helper.py в режиме обновления — ваш существующий токен доступа останется прежним. См. docs/DEPLOYMENT.md.

Plaid Link показывает банк как "unsupported" (часто с Amex). Обычно это проблема INSTITUTION_REGISTRATION_REQUIRED — банки с OAuth требуют предварительной регистрации для каждого учреждения в панели управления Plaid. См. docs/TROUBLESHOOTING.md.

Другие проблемы: docs/TROUBLESHOOTING.md.

Архитектура

• server.py — сервер FastMCP, 9 инструментов только для чтения.

• plaid_client.py — обертка SDK Plaid: маскирование токенов SecretStr, 5-минутный кэш состояния для каждого элемента, форматирование ответов, структурированное отображение ошибок.

• link_helper.py — локальное приложение FastAPI для Plaid Link. Отказывается работать, если установлено HORIZON=1.

Более глубокий разбор (включая причины выбора /transactions/get вместо /transactions/sync): docs/ARCHITECTURE.md.

Участие в разработке

См. CONTRIBUTING.md. Область применения намеренно узкая: только чтение, один пользователь, на базе Plaid.