README.md•10.5 kB
# DeBank MCP Server
> Servidor MCP (Model Context Protocol) para integração com a API do DeBank, permitindo consultar dados DeFi através de IA.
[](https://www.python.org/downloads/)
[](https://github.com/jlowin/fastmcp)
[](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
1. Acesse [DeBank Cloud](https://cloud.debank.com/)
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
```bash
# 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:
```env
DEBANK_ACCESS_KEY=sua_api_key_aqui
```
**⚠️ IMPORTANTE**: Nunca compartilhe ou commit sua API key!
### Passo 4: Testar o Servidor
```bash
# 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:
```bash
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
2. Adicione o servidor DeBank:
```json
{
"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:
```powershell
notepad %APPDATA%\Claude\claude_desktop_config.json
```
2. Use a mesma configuração acima, ajustando os caminhos para Windows:
```json
{
"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:
```bash
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](https://cloud.debank.com/)
- ✅ 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](https://cloud.debank.com/)
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](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](https://cloud.debank.com/) - Obtenha sua API key
- [DeBank API Docs](https://docs.cloud.debank.com/) - Documentação oficial da API
- [FastMCP](https://github.com/jlowin/fastmcp) - Framework MCP usado neste projeto
- [Claude Desktop](https://claude.ai/download) - Cliente MCP oficial da Anthropic
- [MCP Protocol](https://modelcontextprotocol.io/) - Especificação do protocolo MCP
- [DeBank Platform](https://debank.com/) - 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**