DeBank MCP Server

Servidor MCP (Model Context Protocol) para integração com a API do DeBank, permitindo consultar dados DeFi através de IA.

License

📋 Sobre

O DeBank MCP Server é um servidor MCP que conecta a poderosa API do DeBank com assistentes de IA como o Claude Desktop. Com ele, você pode consultar dados DeFi de forma natural através de conversação, incluindo:

💰 Saldos e portfolios de carteiras
🪙 Informações de tokens e preços
🎨 Coleções de NFTs
🏦 Posições em protocolos DeFi
📊 Histórico de transações
🔒 Análise de segurança de approvals
⛽ Preços de gas em tempo real
E muito mais!

✨ Funcionalidades

Core Tools (4)

Chains: Lista todas as blockchains suportadas (93+ chains)
Protocols: Informações de protocolos DeFi com TVL
Tokens: Preços, metadados e holders de tokens
Balance: Saldo total de carteiras across chains

Portfolio Tools (5)

User Tokens: Holdings de tokens com paginação
User NFTs: Coleções de NFTs com metadados
User Protocols: Posições DeFi (simple/complex)
User History: Histórico de transações
User Approvals: Análise de segurança de approvals

Advanced Tools (6)

Net Curve: Tendências de valor em 24h
Pool Info: Analytics de liquidity pools
Transaction Simulation: Simula transações antes de enviar
Gas Prices: Preços de gas por tier
Account Units: Monitoramento de uso da API
User Social: Placeholder para futuro OAuth

Total: 15 ferramentas totalmente funcionais!

🚀 Instalação

Pré-requisitos

Python 3.10 ou superior
Conta no DeBank Cloud (para obter API key)
Claude Desktop (ou outro cliente MCP)

Passo 1: Obter API Key do DeBank

Acesse DeBank Cloud
Crie uma conta ou faça login
Navegue até a seção de API
Copie sua Access Key

Passo 2: Instalar o Servidor

# Clone o repositório
git clone https://github.com/caiovicentino/debank-mcp-server.git
cd debank-mcp-server

# Instale as dependências
pip install -e .

Passo 3: Configurar API Key

Crie um arquivo .env na raiz do projeto:

DEBANK_ACCESS_KEY=sua_api_key_aqui

⚠️ IMPORTANTE: Nunca compartilhe ou commit sua API key!

Passo 4: Testar o Servidor

# Teste se está funcionando
python -c "from mcp_server_debank.server import mcp; print('✅ Servidor OK!')"

🔧 Configuração no Claude Desktop

macOS

Edite o arquivo de configuração:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Adicione o servidor DeBank:

{
  "mcpServers": {
    "debank": {
      "command": "python",
      "args": [
        "-m",
        "mcp_server_debank.server"
      ],
      "cwd": "/caminho/para/debank-mcp-server",
      "env": {
        "DEBANK_ACCESS_KEY": "sua_api_key_aqui",
        "PYTHONPATH": "/caminho/para/debank-mcp-server/src"
      }
    }
  }
}

Substitua /caminho/para/debank-mcp-server pelo caminho real
Substitua sua_api_key_aqui pela sua API key do DeBank
Reinicie o Claude Desktop

Windows

Edite o arquivo de configuração:

notepad %APPDATA%\Claude\claude_desktop_config.json

Use a mesma configuração acima, ajustando os caminhos para Windows:

{
  "mcpServers": {
    "debank": {
      "command": "python",
      "args": [
        "-m",
        "mcp_server_debank.server"
      ],
      "cwd": "C:\\caminho\\para\\debank-mcp-server",
      "env": {
        "DEBANK_ACCESS_KEY": "sua_api_key_aqui",
        "PYTHONPATH": "C:\\caminho\\para\\debank-mcp-server\\src"
      }
    }
  }
}

Linux

Edite o arquivo de configuração:

nano ~/.config/Claude/claude_desktop_config.json

Use a mesma configuração do macOS

💡 Exemplos de Uso

Após configurar, você pode fazer perguntas naturais no Claude:

Consultar Saldos

Qual é o saldo total da carteira vitalik.eth?

Informações de Tokens

Me mostre informações sobre o token USDT na Ethereum

Análise de Portfolio

Quais protocolos DeFi a carteira 0x... está usando?

Segurança

Liste os approvals de token da carteira 0x... na Ethereum

Gas Prices

Qual o preço do gas na Ethereum agora?

NFTs

Quantos NFTs a carteira 0x... possui?

Simulação de Transações

Simule esta transação antes de enviar: {dados da transação}

Análise de Pools

Me dê informações sobre o pool 0x... na Ethereum

📊 Estrutura do Projeto

debank-mcp-server/
├── src/
│   └── mcp_server_debank/
│       ├── __init__.py
│       ├── server.py              # Servidor MCP principal
│       ├── client.py              # Cliente HTTP DeBank
│       ├── validators.py          # Validação de inputs
│       ├── models.py              # Modelos Pydantic
│       ├── portfolio_tools.py     # Tools de portfolio
│       └── advanced_tools.py      # Tools avançados
├── tests/                         # Testes (opcional)
├── pyproject.toml                 # Configuração do projeto
├── .env.example                   # Template de configuração
├── .gitignore                     # Arquivos ignorados
└── README.md                      # Esta documentação

🔐 Segurança

✅ Nunca compartilhe sua API key do DeBank
✅ Use arquivo .env para armazenar credenciais
✅ Adicione .env ao .gitignore
✅ Revogue keys comprometidas imediatamente no DeBank Cloud
✅ Monitore o uso da API regularmente usando a tool debank_get_account_units
⚠️ Não exponha sua API key em commits, logs ou screenshots
⚠️ Use a tool de simulação de transações antes de enviar transações reais

🐛 Troubleshooting

Erro: "DEBANK_ACCESS_KEY not found"

Solução: Certifique-se de que o arquivo .env existe e contém sua API key, ou que a variável de ambiente está configurada corretamente no claude_desktop_config.json.

Erro: "MCP tool not found"

Solução:

Reinicie o Claude Desktop completamente (Cmd+Q no macOS e reabra)
Verifique se o caminho cwd no config está correto
Verifique se o PYTHONPATH está apontando para o diretório src

Response muito grande

Solução: Use os parâmetros de paginação nas ferramentas de portfolio:

limit: Reduzir quantidade de resultados (padrão: 20, máximo: 500)
offset: Paginar através dos resultados

Erro 401: Unauthorized

Solução:

Verifique se sua API key está correta
Confirme que a key está ativa no DeBank Cloud
Tente gerar uma nova API key

Erro 429: Rate Limit

Solução:

O servidor implementa retry automático com backoff exponencial
Aguarde alguns segundos entre requisições
Considere fazer upgrade do plano no DeBank Cloud para limites maiores

Erro: "ModuleNotFoundError: No module named 'mcp_server_debank'"

Solução:

Certifique-se de ter executado pip install -e . no diretório raiz
Verifique se o PYTHONPATH no config aponta para o diretório src
Tente reinstalar: pip uninstall mcp-server-debank && pip install -e .

Claude Desktop não está carregando o servidor

Solução:

Abra o menu Developer no Claude Desktop (View > Developer)
Verifique os logs do servidor na aba MCP
Confirme que o arquivo de configuração JSON está válido (use um validador JSON)
Teste o servidor manualmente: python -m mcp_server_debank.server

📈 Limites da API

Rate Limit: Varia por plano (até 100 req/s no plano Pro)
Paginação: Máximo 500 items por página (configurável)
Chains: 93+ blockchains suportadas
Units: Cada chamada consome units da sua cota (monitore com debank_get_account_units)

🤝 Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para:

Fazer fork do projeto
Criar uma branch para sua feature (git checkout -b feature/MinhaFeature)
Commit suas mudanças (git commit -m 'Add: MinhaFeature')
Push para a branch (git push origin feature/MinhaFeature)
Abrir um Pull Request

Ideias para Contribuições

🧪 Adicionar testes unitários e de integração
📚 Melhorar documentação e exemplos
🐛 Reportar e corrigir bugs
✨ Implementar novas ferramentas baseadas em endpoints do DeBank
🌐 Adicionar suporte para outros idiomas
🔧 Melhorar error handling e validações

📝 Changelog

v1.0.0 (2025-01-11)

✅ 15 ferramentas MCP totalmente funcionais
✅ Suporte a 93+ blockchains
✅ Paginação implementada em todas as tools relevantes
✅ Type safety e validação robusta com Pydantic
✅ Error handling completo com retry automático
✅ Production-ready com logging estruturado
✅ Documentação completa em português

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para mais detalhes.

👨‍💻 Autor

Desenvolvido por Caio Vicentino

Para as comunidades:

🌾 Yield Hacker - Maximizando yields em DeFi
💰 Renda Cripto - Educação financeira crypto
🏗️ Cultura Builder - Construindo o futuro com AI

🔗 Links Úteis

DeBank Cloud - Obtenha sua API key
DeBank API Docs - Documentação oficial da API
FastMCP - Framework MCP usado neste projeto
Claude Desktop - Cliente MCP oficial da Anthropic
MCP Protocol - Especificação do protocolo MCP
DeBank Platform - Explore portfolios DeFi

⭐ Apoie o Projeto

Se este projeto foi útil para você, considere:

⭐ Dar uma estrela no GitHub
🐛 Reportar bugs e sugerir melhorias
🤝 Contribuir com código
📢 Compartilhar com a comunidade
💬 Dar feedback sobre sua experiência
🎓 Criar tutoriais e conteúdo educativo

Feito com ❤️ para a comunidade Web3 brasileira