# Stripe MCP Server

Servidor MCP (Model Context Protocol) que expone la API de Stripe a Claude.
Pensado para desplegarse en Railway en **modo solo lectura**.

👉 **Los pasos de despliegue están en [DEPLOY-RAILWAY.md](./DEPLOY-RAILWAY.md).**

---

## Qué hace

Da a Claude 17 herramientas para consultar Stripe: clientes, cobros, pagos,
suscripciones, facturas, catálogo, saldo, transacciones, payouts, eventos y
disputas — más una herramienta genérica que alcanza cualquier endpoint, otra que
resuelve cualquier objeto por su id, y un reporte agregado de ingresos.

| Herramienta | Endpoint |
|---|---|
| `stripe_whoami` | verifica la key, el modo y los permisos |
| `stripe_request` | cualquier endpoint, cualquier método |
| `stripe_get_object` | resuelve cualquier id (`cus_`, `ch_`, `sub_`...) |
| `stripe_search` | `GET /v1/{recurso}/search` |
| `stripe_list_customers` | `GET /v1/customers` |
| `stripe_list_charges` | `GET /v1/charges` |
| `stripe_list_payment_intents` | `GET /v1/payment_intents` |
| `stripe_list_subscriptions` | `GET /v1/subscriptions` |
| `stripe_list_invoices` | `GET /v1/invoices` |
| `stripe_list_products` | `GET /v1/products` |
| `stripe_list_prices` | `GET /v1/prices` |
| `stripe_get_balance` | `GET /v1/balance` |
| `stripe_list_balance_transactions` | `GET /v1/balance_transactions` |
| `stripe_list_payouts` | `GET /v1/payouts` |
| `stripe_list_events` | `GET /v1/events` |
| `stripe_list_disputes` | `GET /v1/disputes` |
| `stripe_revenue_summary` | pagina y suma bruto/comisiones/neto |

---

## Variables de entorno

| Variable | Requerida | Default | Descripción |
|---|---|---|---|
| `STRIPE_API_KEY` | sí | — | Restricted key (`rk_...`) o secret key (`sk_...`) |
| `STRIPE_MCP_TRANSPORT` | en Railway | `stdio` | `http` para servidor remoto |
| `MCP_AUTH_TOKEN` | si `http` | — | Secreto que protege el endpoint. Mínimo 32 caracteres |
| `STRIPE_READ_ONLY` | no | ver abajo | `1` bloquea toda escritura |
| `STRIPE_ALLOW_LIVE_WRITES` | no | `0` | Segunda reja: escrituras con key **live** |
| `STRIPE_API_BASE` | no | `https://api.stripe.com` | Para apuntar a un mock |
| `STRIPE_API_VERSION` | no | — | Fija el header `Stripe-Version` |
| `STRIPE_ACCOUNT` | no | — | Cuenta de Connect (`acct_...`) para todas las llamadas |
| `STRIPE_MAX_CHARS` | no | `20000` | Truncado de respuestas |
| `STRIPE_TIMEOUT` | no | `45` | Timeout en segundos |
| `PORT` | no | `8000` | Railway lo inyecta solo |

---

## Las tres rejas de escritura

Stripe mueve dinero real: un `POST` equivocado reembolsa a un cliente, cancela
una suscripción o borra un registro para siempre. Por eso hay tres candados
independientes, y una escritura tiene que pasar por los tres.

**1. `STRIPE_READ_ONLY` — el default depende del transporte**

- **`stdio` (local):** escrituras **permitidas** por default. Un solo usuario de
  confianza en su propia máquina.
- **`http` (remoto):** escrituras **bloqueadas** por default. Hay que poner
  `STRIPE_READ_ONLY=0` a propósito para habilitarlas.

Olvidar la variable en un despliegue público lo deja en solo lectura, no abierto.

**2. `STRIPE_ALLOW_LIVE_WRITES` — la reja de modo live**

Aunque apagues el read-only, una key **live** sigue rechazando escrituras hasta
que pongas `STRIPE_ALLOW_LIVE_WRITES=1`. Las keys de test (`sk_test_`, `rk_test_`)
no pasan por esta reja: experimentar contra datos de prueba no debe requerir
ceremonia.

**3. `confirm=true` — la reja por endpoint**

Los endpoints destructivos (`/v1/refunds`, `/v1/payouts`, `/v1/transfers`,
cancelaciones de suscripción, borrado de clientes, cierre de disputas) exigen
`confirm=true` en la llamada, además de todo lo anterior. Una herramienta
disparada por error no llega ahí sola.

Cada rechazo dice **cuál** de las tres rejas lo detuvo.

---

## Autenticación del endpoint

El protocolo MCP no trae autenticación propia. En modo `http`, este servidor
exige `Authorization: Bearer <MCP_AUTH_TOKEN>` en cada request, o el secreto
embebido en la ruta (`/s/<secreto>/mcp`) para los connectors de Claude.
`/healthz` es la única ruta pública.

El servidor **se niega a arrancar** si `MCP_AUTH_TOKEN` falta o tiene menos de
32 caracteres. Es a propósito: evita publicar un gateway abierto a tu cuenta de
Stripe por descuido.

---

## Correr en local

```bash
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
```

Al arrancar imprime en qué modo quedó:

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

---

## Notas sobre la API de Stripe

Cosas que el servidor ya resuelve por ti, y que conviene saber al leer las
respuestas:

- **Stripe no acepta JSON en el body.** Todo va `application/x-www-form-urlencoded`
  con notación de corchetes: `metadata[order]=6735`, `expand[]=customer`,
  `items[0][price]=price_1`. El servidor traduce dicts y listas anidadas solo.
- **El dinero es un entero en la unidad mínima.** `2500` con `usd` es $25.00.
  Y hay monedas de cero decimales (JPY, KRW, CLP…) donde el entero *es* el monto
  — dividir entre 100 ahí sería un error. Las salidas formateadas lo respetan.
- **Test y live son universos separados.** Un id creado en test devuelve 404 con
  una key live y viceversa. Es la causa más común de un 404 con un id correcto.
- **La paginación es por cursor, no por página.** Se toma el último id y se pasa
  como `starting_after`. Cuando hay más, la respuesta incluye `next_page_hint`
  con el valor exacto.
- **No hay `PATCH` ni `PUT`.** Stripe usa `POST` tanto para crear como para
  actualizar. Solo `GET`, `POST` y `DELETE`.
- **Las listas no filtran por `status`** en charges ni payment_intents. Hay que
  filtrar sobre los registros devueltos o usar `stripe_search`.
- **`stripe_list_subscriptions` omite las canceladas por default.** Para
  preguntas de churn hay que pasar `status='all'` o la respuesta sale mal en
  silencio.
- **El índice de búsqueda tarda hasta un minuto** en ver un objeto recién creado.
  Para objetos nuevos, buscarlos por id.
- **Los eventos se guardan solo 30 días.** Más atrás hay que ir a los objetos.
- **No hay endpoint de agregación.** Por eso `stripe_revenue_summary` pagina y
  suma del lado del servidor MCP, y avisa con `complete=false` cuando el tope de
  páginas cortó el conteo — esos totales son parciales y no deben reportarse
  como finales.
- Cada `POST` sale con un `Idempotency-Key`, así que un reintento no cobra dos
  veces. Stripe los recuerda 24 horas.

---

## Seguridad

- Los secretos van en variables de entorno, nunca en el código. El `.gitignore`
  bloquea archivos `.env`.
- **Usa una restricted key (`rk_...`), no la secret key.** Se crean en el
  dashboard cuantas veces quieras y se les dan permisos por recurso. Para este
  despliegue: todo en *Read*, nada en *Write*. Una `sk_live_` da acceso total a
  la cuenta, incluido mover dinero.
- Un solo token compartido significa cero trazabilidad por persona. Todo lo que
  haga cualquiera queda registrado como la misma key.
- No hay rate limiting propio. Quien tenga el `MCP_AUTH_TOKEN` puede pegarle a
  Stripe hasta toparse con el límite de Stripe (~100 req/s de lectura en live).
- Para cortar el acceso de golpe: borra la restricted key en
  https://dashboard.stripe.com/apikeys — el servidor queda inútil al instante.