Splitwise MCP Server

Gerencie despesas do Splitwise em inglês simples via Claude AI — adicione despesas, verifique saldos e acerte contas sem abrir o aplicativo.

GitHub

Experimente este MCPPatrocinado

Documentação

Servidor MCP Splitwise — Controle o Splitwise em Português Simples

"Adicione um jantar de ₩45.000, eu paguei, dividir igualmente." Pronto. Sem aplicativo. Sem toques. Sem matemática.

Por Que Eu Construí Isso

Eu estava prestes a viajar com amigos e já estava temendo o controle de despesas.

Você sabe como funciona — alguém paga o jantar, outro pega o táxi, outra pessoa cobre o depósito do hotel. No segundo dia, você já perdeu o controle. Então você abre o Splitwise, navega por quatro telas, digita o valor, seleciona as pessoas, escolhe quem pagou, salva. Depois faz de novo para a próxima coisa. E a próxima.

Pensei: Já estou usando o Claude para tudo. E se eu pudesse simplesmente dizer o que aconteceu, e ele cuidasse do Splitwise para mim?

Então construí isso em um fim de semana. É um pequeno servidor Python que conecta o Claude AI diretamente à sua conta Splitwise. Você fala com o Claude como um humano, e ele faz o trabalho do Splitwise para você — adicionando despesas, verificando saldos, registrando acertos, corrigindo erros.

Sem alternar de aplicativo. Sem entrada manual. Apenas diga o que aconteceu.

Como É Usar

You:    "We had a group dinner for ₩65,000. I paid. Split equally."
Claude: Done! Added "Group dinner" for ₩65,000.00 (KRW), split equally
        among 4 members. Each person owes ₩16,250.

You:    "What does everyone owe in the trip group?"
Claude: Here are the current balances:
        • Raj owes you ₩32,500
        • Priya owes you ₩16,250
        • Sam is owed ₩8,000 by the group

You:    "Record that Raj paid me back ₩30,000."
Claude: Payment of ₩30,000 recorded. Raj's balance updated.

You:    "Wait, that dinner was actually ₩72,000. Can you fix it?"
Claude: Updated! "Group dinner" changed to ₩72,000. Shares recalculated.

Funciona com qualquer moeda que o Splitwise suporta — USD, EUR, INR, KRW, JPY e mais.

Como Funciona (A Versão Simples)

You talk to Claude
       ↓
Claude understands what you want
       ↓
Claude calls this MCP server
       ↓
This server calls the Splitwise API
       ↓
Your Splitwise account updates instantly
       ↓
Everyone's app reflects the change

MCP (Model Context Protocol) é uma forma padrão de dar ao Claude acesso a ferramentas externas. Este projeto é a "ferramenta Splitwise" — uma ponte entre o Claude e sua conta Splitwise.

Veja architecture.md para um diagrama detalhado de como tudo se conecta.

O Que Você Pode Fazer

Peça ao Claude	O Que Acontece
"Liste meus grupos"	Mostra todos os seus grupos Splitwise com membros
"Quem deve o quê no [grupo]?"	Mostra todos os saldos
"Adicione um almoço de $52, eu paguei, dividir igualmente"	Cria a despesa
"Adicione hotel de $240 — eu paguei $120, Alex $80, Sam $40"	Divisão exata
"Divida o táxi de $35 em 50/30/20"	Divisão percentual
"Registre que Alex me pagou $20"	Pagamento de acerto
"Exclua a última despesa"	Remove-a
"Mude o jantar para $60"	Atualiza e recalcula

Configuração

O Que Você Vai Precisar

Python 3.10+ (python3 --version para verificar)
Uma conta Splitwise + chave de API de secure.splitwise.com/apps
Claude Desktop ou Claude Code

Passo 1: Clone e instale

git clone https://github.com/yourusername/splitwise-mcp.git
cd splitwise-mcp
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Passo 2: Adicione sua chave de API

Crie um arquivo chamado .env na pasta do projeto:

SPLITWISE_API_KEY=paste_your_key_here

Onde obter sua chave:

Vá para secure.splitwise.com/apps
Clique em "Register your application"
Preencha qualquer nome (ex.: "My MCP Server")
Copie a API Key para o seu arquivo .env

Passo 3: Conecte ao Claude Desktop

Edite ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "splitwise": {
      "command": "/full/path/to/venv/bin/python3",
      "args": ["/full/path/to/splitwise_server.py"]
    }
  }
}

Reinicie o Claude Desktop. Você verá um ícone de martelo — isso significa que as ferramentas estão conectadas.

Passo 4 (Opcional): Hospede em um Servidor para Acesso 24/7

Quer que funcione mesmo quando seu laptop está desligado? Implante em qualquer VPS (eu uso Hostinger).

Veja DEPLOY.md para o guia completo passo a passo.

Depois de hospedado, conecte o Claude Desktop via:

{
  "mcpServers": {
    "splitwise": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://YOUR_SERVER_IP:8000/mcp", "--allow-http"]
    }
  }
}

Todas as Ferramentas Disponíveis

Ferramenta	O Que Ela Faz
`get_current_user`	Seu perfil Splitwise
`list_currencies`	Todas as moedas que o Splitwise suporta
`list_groups`	Todos os seus grupos com IDs de membros
`get_group`	Detalhes do grupo — membros, saldos, dívidas
`list_expenses`	Despesas recentes em um grupo
`get_expense`	Detalhes completos de uma despesa
`create_expense`	Adicionar despesa (divisão igual, exata ou percentual)
`update_expense`	Editar descrição, custo, moeda ou data
`delete_expense`	Remover uma despesa
`create_payment`	Registrar um acerto entre duas pessoas

Solução de Problemas

Problema	Correção
Claude não vê as ferramentas Splitwise	Reinicie o Claude Desktop após editar a configuração
Erro 401 Unauthorized	Verifique se sua chave de API em `.env` está correta
"No module named mcp"	Ative seu venv: `source venv/bin/activate`
Servidor desconectado	Verifique se o servidor está rodando: `sudo systemctl status splitwise-mcp`
Caminhos errados na configuração	Use caminhos absolutos completos, não relativos

Estrutura do Projeto

splitwise-mcp/
├── splitwise_server.py   ← The entire server (~500 lines, one file)
├── .env                  ← Your API key (never committed to git)
├── requirements.txt      ← Python dependencies
├── architecture.md       ← How everything connects
├── DEPLOY.md             ← How to host on a VPS
└── README.md             ← This file

Construído Com

FastMCP — framework MCP em Python
Splitwise REST API v3
httpx — cliente HTTP
Hospedado em VPS Hostinger (Ubuntu)

Construído por um desenvolvedor Python de primeira viagem que só queria parar de registrar despesas de viagem manualmente. Se eu consegui construir, você consegue usar.

Licença

MIT — use como quiser.