Stripe MCP — Casos de uso, Instalar & Demo ao vivo

Name: Stripe MCP Server
Author: stripe

Por que usar

Principais recursos

Ler e escrever nos principais recursos do Stripe
Alternação entre modo de teste e modo ao vivo via chave API
Pesquisa poderosa (consultas estilo stripe.search)
Seleção de ferramenta via --tools= CLI arg — restringe para somente leitura por segurança
Mantido diretamente pela Stripe

Demo ao vivo

Como fica na prática

stripe.replay ▶ pronto

0/0

Instalar

Escolha seu cliente

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": [
        "-y",
        "@stripe/mcp",
        "--tools=all"
      ]
    }
  }
}

Abra Claude Desktop → Settings → Developer → Edit Config. Reinicie após salvar.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": [
        "-y",
        "@stripe/mcp",
        "--tools=all"
      ]
    }
  }
}

Cursor usa o mesmo esquema mcpServers que o Claude Desktop. Config de projeto vence a global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": [
        "-y",
        "@stripe/mcp",
        "--tools=all"
      ]
    }
  }
}

Clique no ícone MCP Servers na barra lateral do Cline, depois "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "stripe": {
      "command": "npx",
      "args": [
        "-y",
        "@stripe/mcp",
        "--tools=all"
      ]
    }
  }
}

Mesmo formato do Claude Desktop. Reinicie o Windsurf para aplicar.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "stripe",
      "command": "npx",
      "args": [
        "-y",
        "@stripe/mcp",
        "--tools=all"
      ]
    }
  ]
}

O Continue usa um array de objetos de servidor em vez de um map.

~/.config/zed/settings.json

{
  "context_servers": {
    "stripe": {
      "command": {
        "path": "npx",
        "args": [
          "-y",
          "@stripe/mcp",
          "--tools=all"
        ]
      }
    }
  }
}

Adicione em context_servers. Zed recarrega automaticamente ao salvar.

claude mcp add stripe -- npx -y @stripe/mcp --tools=all

Uma linha só. Verifique com claude mcp list. Remova com claude mcp remove.

Casos de uso

Usos do mundo real: Stripe

Investigue por que as cobranças de um cliente estão falhando

👤 Engenheiros de suporte, fundadores fazendo atendimento de primeira linha ⏱ ~10 min beginner

Quando usar: O cliente diz 'meu cartão foi recusado 3 vezes'. Você quer ver o que realmente aconteceu do lado de Stripe.

Pré-requisitos

Distribuir chave de API restrita com leitura de cobranças/clientes — dashboard.stripe.com/apikeys → Chaves restritas → conceder leitura sobre clientes, cobranças, intenções de pagamento

Fluxo

Encontre o cliente

Encontre o cliente Stripe com o e-mail '[email protected]'. Mostre a forma de pagamento padrão e o gasto total.✓ Copiado

→ Registro do cliente com detalhes da forma de pagamento
Extrair cobranças com falha recentes

Liste as cobranças deste cliente nos últimos 30 dias em que o status != 'bem-sucedido'. Para cada um, mostre o código de falha e a mensagem.✓ Copiado

→ Lista de falhas com card_declined/expired_card/etc. códigos
Explicar e recomendar ações

Qual é o problema real? Recomende o que dizer ao cliente (por exemplo, 'cartão expirou – atualize' ou 'bloqueio de fraude - tente um cartão diferente').✓ Copiado

→ Explicação clara voltada para o cliente

Resultado: Resolvido ticket de suporte com a causa real, não 'tente novamente mais tarde'.

Armadilhas

Olhando apenas para cobranças – perde intenções de pagamento que nunca chegaram a ser cobradas — Verifique também as Intenções de Pagamento com status 'requires_payment_method' ou 'cancelado'
Cliente diz ‘recusou’, mas foi abandono do 3DS — Os desafios 3DS que o usuário fecha são exibidos como requires_action e expiram; verifique o cronograma

Crie uma fatura de teste e um link de pagamento para uma transação

👤 Pessoal de vendas e operações fechando negócios personalizados ⏱ ~5 min beginner

Quando usar: Você concordou com um preço personalizado único com um cliente e precisa de uma fatura ou link de pagamento rapidamente.

Pré-requisitos

Tecla do modo TESTE (sk_test_...) — Sempre inicie no modo de teste. Mude para a chave ativa somente depois que o fluxo for validado.

Fluxo

Encontre ou crie o cliente

Procure o cliente Stripe com o e-mail '[email protected]'. Se não houver, crie um com o nome 'BigCo Inc'.✓ Copiado

→ ID do cliente retornado
Crie um item único de preço + fatura

Crie um item de fatura único: US$ 4.500, descrição 'Serviços de integração do segundo trimestre'. Anexe a esse cliente. Em seguida, crie e finalize uma fatura.✓ Copiado

→ Fatura com host_invoice_url
Confirmar entrega

Forneça o URL da fatura hospedada e um resumo do que foi criado. Não envie por e-mail - encaminharei manualmente.✓ Copiado

→ URL + resumo; nenhum e-mail surpresa enviado

Resultado: Uma fatura que você pode enviar ao cliente em 90 segundos.

Armadilhas

Enviar e-mail automático aos clientes pelo chat é uma arma de fogo — Use auto_advance: false e pule send_invoice até revisar; o MCP não deve enviar e-mails aos clientes de produção sem confirmação explícita
Mistura de modo teste/ao vivo significa fluxo de dinheiro real para um ‘teste’ — Sempre inspecione o prefixo da chave API (sk_test_ vs sk_live_) antes de qualquer mutação; faça o MCP repetir de volta

Combine com: supabase

Calcule o MRR atual e a rotatividade das assinaturas do Stripe

👤 Fundadores realizando operações financeiras ⏱ ~15 min intermediate

Quando usar: Revisão mensal; você deseja uma leitura rápida de MRR/rotatividade diretamente da fonte.

Fluxo

Extrair assinaturas ativas

Liste todas as assinaturas ativas do Stripe (status='active' ou 'trialing'). Agrupe por price_id, some o equivalente ao MRR.✓ Copiado

→ Totais por preço + total geral
Pull cancelado este mês

Listar assinaturas canceladas nos últimos 30 dias. Para cada um, mostre a data de início, o MRR contribuído e o cliente.✓ Copiado

→ Lista de rotatividade com impacto na receita
Calcular o novo MRR líquido

Novo MRR líquido = novo este mês - rotatividade este mês. Calcule e escreva um resumo de 3 linhas.✓ Copiado

→ Número único com detalhamento de cálculo

Resultado: Um instantâneo preciso do MRR que você pode colar em sua revisão mensal.

Armadilhas

Planos anuais precisam de normalização mensal — Divida o preço anual por 12 ao somar o MRR; o MCP não faz isso por você
Descontos e créditos distorcem o valor bruto versus líquido — Decidir a convenção MRR (bruto vs líquido de descontos) e aplicá-la de forma consistente

Combine com: filesystem

Processe um reembolso com proteções apropriadas

👤 Leads de suporte com autoridade de reembolso ⏱ ~5 min beginner

Quando usar: O cliente solicita um reembolso; você deseja verificar a cobrança e processá-la de forma limpa.

Pré-requisitos

Chave API com reembolsos:write — Chave restrita, conceda apenas os escopos mínimos

Fluxo

Encontre e valide a cobrança

Encontre a carga Stripe ch_xxx. Mostre valor, cliente, status e se já foi reembolsado (parcial ou total).✓ Copiado

→ Detalhes de cobrança + histórico de reembolso
Visualizar o reembolso

Quero reembolsar $ 50 de $ 200 (parcial). Mostre-me como seria a chamada de reembolso. Não execute ainda.✓ Copiado

→ Visualização simulada da chamada de API
Executar na confirmação

Prossiga com o reembolso parcial. Devolva o ID do reembolso e o estado de cobrança atualizado.✓ Copiado

→ Reembolso criado, cobrança marcada como parcialmente_reembolsada

Resultado: Reembolso processado de forma limpa com trilha de auditoria.

Armadilhas

O reembolso de mais do que a cobrança original falha de forma confusa — Verifique sempre o saldo restante reembolsável antes de solicitar; o MCP ecoa o limite
O reembolso aciona o webhook para seu aplicativo – pode atualizar duas vezes o estado interno — Coordene o fluxo de reembolso com quem mantém o gerenciador de webhook

Saldo de auditoria e pagamentos recentes antes do encerramento do trimestre

👤 Finanças, fundadores ⏱ ~10 min intermediate

Quando usar: No final do trimestre, você quer saber exatamente o que está no Stripe e o que está prestes a chegar ao banco.

Fluxo

Obtenha o detalhamento do saldo atual

Mostrar saldo atual do Stripe: disponível, pendente, em trânsito. Divida por moeda.✓ Copiado

→ Saldo por moeda triplo
Listar pagamentos recentes

Liste os pagamentos nos últimos 90 dias com data, valor, status e data de chegada. Classificar por data desc.✓ Copiado

→ Cronograma de pagamentos com totais
Reconcilie-se com seus livros

Qual o valor total de pagamento no período? Diga-me o que esperar para chegar ao banco nos próximos 7 dias.✓ Copiado

→ Total agregado do período + previsão de curto prazo

Resultado: Um resumo pronto para reconciliação.

Armadilhas

Reservas e fundos disputados não estão 'disponíveis' — Não iguale saldo.disponível + saldo.pendente = caixa total; verificar os saldos retidos separadamente

Combine com: filesystem

Combinações

Combine com outros MCPs para 10× de alavancagem

stripe + supabase

Stripe webhook → Supabase Edge Function → Stripe consultas MCP para enriquecer o tratamento de eventos

Quando o webhook 'invoice.payment_failed' do Stripe é acionado, o Edge Function chama o Stripe MCP para buscar as cobranças recentes do cliente e cola um resumo em nosso canal de operações do Slack.✓ Copiado

stripe + postgres

Reconcilie as cobranças do Stripe com seu banco de dados de pedidos internos

Para cada cobrança bem-sucedida do Stripe ontem, encontre a linha correspondente em nossa tabela orders por stripe_payment_intent_id. Incompatibilidades de sinalização.✓ Copiado

stripe + filesystem

Exporte dados do Stripe para CSV para a equipe financeira

Exporte todas as faturas do último trimestre para /reports/invoices-Q1-2026.csv com e-mail do cliente, valor, status e data.✓ Copiado

Ferramentas

O que este MCP expõe

Ferramenta	Entradas	Quando chamar	Custo
list_customers / retrieve_customer / create_customer / update_customer	Stripe customer params	CRUD do cliente	free Stripe API
list_products / create_product / update_product	product params	Operações de catálogo de produtos	free
list_prices / create_price	price params	Operações de preço (únicas ou recorrentes)	free
list_invoices / create_invoice / finalize_invoice / pay_invoice	invoice params	Ciclo de vida da fatura	free
create_invoice_item	customer, amount, currency, description	Adicionar uma linha a um rascunho de fatura	free
list_payment_intents / retrieve_payment_intent	PI params	Inspecione o estado do fluxo de pagamento	free
list_charges / retrieve_charge	charge params	Inspeção de cobrança	free
create_refund	charge: str, amount?: int	Emitir um reembolso total ou parcial – destrutivo no modo ao vivo	free Stripe API; refund itself moves money
create_payment_link	line_items, after_completion?	Gere um URL de pagamento hospedado para enviar a um cliente	free
list_subscriptions / cancel_subscription / update_subscription	subscription params	Ciclo de vida da assinatura	free
retrieve_balance	none	Saldo atual disponível/pendente	free
list_payouts	limit, created?	Veja pagamentos recentes e futuros	free
search_*	query: str (Stripe Search syntax)	Filtragem poderosa entre recursos por meio da API de pesquisa	free

Custo e limites

O que custa rodar

Cota de API: A API Stripe tem limites de taxa generosos (100 req/s lidos em tempo real, 25 req/s em teste por padrão)
Tokens por chamada: Objetos Stripe são pesados em tokens (dados aninhados ricos). Use expandir somente quando necessário; tamanhos de lista de limites
Monetário: MCP grátis; Stripe cobra por pagamento processado, não por chamada de API
Dica: No modo de teste, os custos são zero. No modo ao vivo, o único “custo” que importa são reembolsos ou faturas emitidas acidentalmente – gravações de portão com filtragem --tools=.

Segurança

Permissões, segredos, alcance

Escopos mínimos: restricted key with the minimum scopes per workflow (e.g. Customers:read + Charges:read for support)

Armazenamento de credenciais: Chave de API em env var STRIPE_SECRET_KEY. Nunca se comprometa. Use chaves restritas, não a chave secreta raiz.

Saída de dados: Todas as chamadas para api.stripe.com (TLS, PCI gerenciado pelo Stripe)

Nunca conceda: root secret key to long-running agents API key with Refunds:write or Subscriptions:write to autonomous workflows without HITL

O modo ao vivo significa dinheiro real. Sempre confirme o prefixo da chave (sk_live_ vs sk_test_) antes de qualquer chamada de gravação.
Use o sinalizador CLI --tools= (por exemplo, --tools=customers.read,charges.read) para restringir o MCP a um subconjunto seguro.
Webhooks atualizam o estado interno – coordenam reembolsos e cancelamentos com a engenharia.

Solução de problemas

Erros comuns e correções

401 Invalid API Key

Chave errada, revogada ou incompatibilidade de teste/ao vivo. Verifique no painel. Confirme se env var foi exportado para o processo do cliente MCP.

Verificar: curl https://api.stripe.com/v1/balance -u $STRIPE_SECRET_KEY:

Permission denied: this key has no access to ...

Restricted key missing the relevant scope. Edit the key in dashboard to grant the needed permission.

Refund: amount exceeds remaining refundable

Charge already partially refunded. Retrieve the charge first, check amount_refunded, refund only the remainder.

Search returns 0 results despite the object existing

Stripe Search has a propagation delay (~1 minute for newly-created objects). Use list/retrieve for very recent items.

Alternativas

Stripe vs. outros

Alternativa	Quando usar	Troca
Stripe CLI via shell	You want webhook forwarding, fixture generation, or local testing flows	No agent ergonomics; meant for dev workflows
Direct REST API via fetch MCP	You need a feature the official MCP doesn't expose	Auth, pagination, and types are all manual; way more error-prone

Mais

Recursos

📖 Leia o README oficial no GitHub

🐙 Ver issues abertas

🔍 Ver todos os 400+ servidores MCP e Skills