DeBank MCP Server

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

📋 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

1. Acesse DeBank Cloud

2. Crie uma conta ou faça login

3. Navegue até a seção de API

4. 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

1. Edite o arquivo de configuração:

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

2. 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"
      }
    }
  }
}

3. Substitua /caminho/para/debank-mcp-server pelo caminho real

4. Substitua sua_api_key_aqui pela sua API key do DeBank

5. Reinicie o Claude Desktop

Windows

1. Edite o arquivo de configuração:

notepad %APPDATA%\Claude\claude_desktop_config.json

2. 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

1. Edite o arquivo de configuração:

nano ~/.config/Claude/claude_desktop_config.json

2. 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:

1. Reinicie o Claude Desktop completamente (Cmd+Q no macOS e reabra)

2. Verifique se o caminho cwd no config está correto

3. 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:

1. Verifique se sua API key está correta

2. Confirme que a key está ativa no DeBank Cloud

3. 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:

1. Certifique-se de ter executado pip install -e . no diretório raiz

2. Verifique se o PYTHONPATH no config aponta para o diretório src

3. Tente reinstalar: pip uninstall mcp-server-debank && pip install -e .

Claude Desktop não está carregando o servidor

Solução:

1. Abra o menu Developer no Claude Desktop (View > Developer)

2. Verifique os logs do servidor na aba MCP

3. Confirme que o arquivo de configuração JSON está válido (use um validador JSON)

4. 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:

1. Fazer fork do projeto

2. Criar uma branch para sua feature (git checkout -b feature/MinhaFeature)

3. Commit suas mudanças (git commit -m 'Add: MinhaFeature')

4. Push para a branch (git push origin feature/MinhaFeature)

5. 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