Stripe MCP Server

Сервер MCP (Model Context Protocol), который предоставляет API Stripe для Claude. Предназначен для развёртывания на Railway в режиме только для чтения.

👉 Шаги развёртывания находятся в DEPLOY-RAILWAY.md.

Что он делает

Даёт Claude 17 инструментов для запросов к Stripe: клиенты, платежи, оплаты, подписки, счета, каталог, баланс, транзакции, выплаты, события и споры — плюс универсальный инструмент, который обращается к любому endpoint'у, ещё один, который разрешает любой объект по его id, и агрегированный отчёт о доходах.

Related MCP server: Stripe MCP Server

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

Три решётки записи

Stripe работает с реальными деньгами: неверный POST возвращает средства клиенту, отменяет подписку или навсегда удаляет запись. Поэтому есть три независимых замка, и запись должна пройти через все три.

1. STRIPE_READ_ONLY — значение по умолчанию зависит от транспорта

• stdio (локально): записи разрешены по умолчанию. Один доверенный пользователь на своей машине.

• http (удалённо): записи заблокированы по умолчанию. Нужно намеренно установить STRIPE_READ_ONLY=0, чтобы их включить.

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

2. STRIPE_ALLOW_LIVE_WRITES — решётка live-режима

Даже если вы отключите read-only, ключ live по-прежнему отклоняет записи, пока вы не установите STRIPE_ALLOW_LIVE_WRITES=1. Тестовые ключи (sk_test_, rk_test_) не проходят через эту решётку: экспериментировать с тестовыми данными не должно требовать церемоний.

3. confirm=true — решётка по endpoint'у

Деструктивные endpoint'ы (/v1/refunds, /v1/payouts, /v1/transfers, отмена подписок, удаление клиентов, закрытие споров) требуют confirm=true в вызове, помимо всего вышеперечисленного. Инструмент, запущенный по ошибке, не дойдёт туда сам.

Каждый отказ сообщает, какая из трёх решёток его остановила.

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

Протокол MCP не имеет собственной аутентификации. В режиме http этот сервер требует Authorization: Bearer <MCP_AUTH_TOKEN> в каждом запросе, либо секрет, встроенный в путь (/s/<секрет>/mcp) для коннекторов Claude. /healthz — единственный публичный маршрут.

Сервер отказывается запускаться, если MCP_AUTH_TOKEN отсутствует или имеет менее 32 символов. Это намеренно: предотвращает случайную публикацию открытого шлюза к вашему аккаунту Stripe.

Запуск локально

pip install -r requirements.txt

# stdio (para Claude Desktop)
STRIPE_API_KEY=rk_test_xxx python stripe_mcp.py

# http (como en Railway)
STRIPE_MCP_TRANSPORT=http \
STRIPE_API_KEY=rk_test_xxx \
MCP_AUTH_TOKEN=$(python3 -c "import secrets;print(secrets.token_urlsafe(48))") \
PORT=8000 python stripe_mcp.py

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

[stripe-mcp] streamable-http on 0.0.0.0:8000  mode=test  read_only=True  allow_live_writes=False  writes_enabled=False

Заметки об API Stripe

Вещи, которые сервер уже решает за вас, и которые полезно знать при чтении ответов:

• Stripe не принимает JSON в теле. Всё идёт application/x-www-form-urlencoded с нотацией квадратных скобок: metadata[order]=6735, expand[]=customer, items[0][price]=price_1. Сервер переводит только вложенные dict'ы и списки.

• Деньги — это целое число в минимальной единице. 2500 с usd — это $25.00. И есть валюты с нулём десятичных знаков (JPY, KRW, CLP…), где целое и есть сумма — делить на 100 там было бы ошибкой. Форматированные выходные данные это учитывают.

• Test и live — это отдельные вселенные. id, созданный в test, возвращает 404 с live-ключом и наоборот. Это самая частая причина 404 с правильным id.

• Пагинация по курсору, а не по страницам. Берётся последний id и передаётся как starting_after. Когда есть ещё, ответ включает next_page_hint с точным значением.

• Нет PATCH или PUT. Stripe использует POST как для создания, так и для обновления. Только GET, POST и DELETE.

• Списки не фильтруют по status в charges и payment_intents. Нужно фильтровать по возвращённым записям или использовать stripe_search.

• stripe_list_subscriptions по умолчанию пропускает отменённые. Для вопросов о churn нужно передать status='all', иначе ответ будет неверным молча.

• Индекс поиска занимает до минуты, чтобы увидеть только что созданный объект. Для новых объектов ищите их по id.

• События хранятся только 30 дней. Для более ранних нужно обращаться к объектам.

• Нет endpoint'а агрегации. Поэтому stripe_revenue_summary разбивает на страницы и суммирует на стороне MCP-сервера, и предупреждает с complete=false, когда лимит страниц прервал подсчёт — эти итоги частичные и не должны сообщаться как окончательные.

• Каждый POST выходит с Idempotency-Key, так что повторная попытка не списывает дважды. Stripe хранит их 24 часа.

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

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

• Используйте restricted key (rk_...), а не secret key. Их можно создавать в дашборде сколько угодно раз и давать разрешения по ресурсам. Для этого развёртывания: всё на Read, ничего на Write. sk_live_ даёт полный доступ к аккаунту, включая перемещение денег.

• Один общий токен означает нулевую трассируемость по людям. Всё, что делает кто-либо, записывается как один и тот же ключ.

• Нет собственного rate limiting. Тот, у кого есть MCP_AUTH_TOKEN, может обращаться к Stripe, пока не упрётся в лимит Stripe (~100 req/s чтения в live).

• Чтобы мгновенно прекратить доступ: удалите restricted key на https://dashboard.stripe.com/apikeys — сервер станет бесполезным сразу.