DeBank MCP Server
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@DeBank MCP Server show me the total balance for vitalik.eth"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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!
Related MCP server: Datai MCP Server
✨ 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.jsonAdicione 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-serverpelo caminho realSubstitua
sua_api_key_aquipela sua API key do DeBankReinicie o Claude Desktop
Windows
Edite o arquivo de configuração:
notepad %APPDATA%\Claude\claude_desktop_config.jsonUse 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.jsonUse 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 EthereumAnálise de Portfolio
Quais protocolos DeFi a carteira 0x... está usando?Segurança
Liste os approvals de token da carteira 0x... na EthereumGas 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
.envpara armazenar credenciais✅ Adicione
.envao.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
cwdno config está corretoVerifique se o
PYTHONPATHestá apontando para o diretóriosrc
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 raizVerifique se o
PYTHONPATHno config aponta para o diretóriosrcTente 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
Available Tools
16 toolsdebank_get_account_units_toolA
Check API units balance and 30-day usage from DeBank.
Monitor your API consumption to plan usage and avoid running out of units.
Returns: balance: Remaining units (integer) stats: Array of 30 days usage history usage_analysis: Summary with total usage, daily average, days remaining, peak usage day, and recommendations
Inputs: no named parameters. Returns: object
debank_get_chainsA
Get blockchain network information from DeBank.
This tool retrieves comprehensive information about blockchain networks supported by DeBank, including network details, native tokens, and protocol counts.
Args: chain_id: Optional chain ID. If provided, returns single chain info. If None, returns all supported chains. Examples: "eth", "bsc", "polygon", "arbitrum", "optimism"
Returns: Chain object(s) with the following structure: { "id": "eth", "name": "Ethereum", "logo_url": "https://...", "native_token_id": "eth", "wrapped_token_id": "0xc02...", "is_support_pre_exec": true }
Examples: - Get all chains: debank_get_chains() - Get Ethereum: debank_get_chains(chain_id="eth") - Get Binance Smart Chain: debank_get_chains(chain_id="bsc")
Inputs: chain_id. Returns: object
debank_get_gas_prices_toolA
Get current gas prices for a blockchain from DeBank.
Monitor gas prices to optimize transaction timing and costs.
Args: chain_id: Blockchain ID (required)
Returns: Gas price tiers (slow, normal, fast, instant) with cost estimates for common transaction types
Inputs: chain_id (required). Returns: object
debank_get_pool_info_toolA
Get liquidity pool information from DeBank.
Analyze liquidity pool metrics including TVL, user counts, and statistics.
Args: pool_id: Pool identifier/contract address (required, must start with 0x) chain_id: Blockchain ID (required)
Returns: Pool object with enhanced summary metrics including TVL, user counts, average deposit size, and valuable user ratio
Inputs: pool_id (required), chain_id (required). Returns: object
debank_get_protocolsA
Get DeFi protocol information from DeBank.
This tool retrieves comprehensive information about DeFi protocols, including TVL (Total Value Locked), supported chains, and protocol metadata.
Args: protocol_id: Optional specific protocol ID (e.g., 'uniswap', 'aave', 'compound', 'curve', 'lido', 'makerdao') chain_id: Optional filter by chain (e.g., 'eth', 'bsc', 'polygon') all_chains: If True, get all protocols across all chains
Returns: Protocol object(s) with the following structure: { "id": "uniswap", "name": "Uniswap", "chain": "eth", "logo_url": "https://...", "tvl": 5234567890, "portfolio_item_list": [...] }
Examples: - Get all protocols on Ethereum: debank_get_protocols(chain_id="eth") - Get specific protocol: debank_get_protocols(protocol_id="uniswap") - Get all protocols: debank_get_protocols(all_chains=True) - Get Aave on Polygon: debank_get_protocols(protocol_id="aave", chain_id="polygon")
Inputs: chain_id, all_chains, protocol_id. Returns: object
debank_get_token_holdersA
Get top holders of a token from DeBank.
This tool retrieves the largest holders of a specific token, useful for analyzing token distribution and whale activity.
Args: chain_id: Blockchain ID (required). Examples: "eth", "bsc", "polygon" token_id: Token contract address (required, must start with 0x) limit: Number of holders to return (max 100, default 100) offset: Starting position for pagination (max 10000, default 0)
Returns: Object with holder data: { "holders": [ { "address": "0x5853ed4f26a3fcea565b3fbc698bb19cdf6deb85", "amount": "1234567890000000000", "usd_value": 1234567.89 }, ... ], "total_count": 50000 }
Examples: - Get top 100 USDT holders: debank_get_token_holders( chain_id="eth", token_id="0xdac17f958d2ee523a2206206994597c13d831ec7" ) - Get next 50 holders: debank_get_token_holders( chain_id="eth", token_id="0xdac17f958d2ee523a2206206994597c13d831ec7", limit=50, offset=100 )
Inputs: chain_id (required), token_id (required), limit, offset. Returns: object
debank_get_token_infoA
Get token information and prices from DeBank.
This tool retrieves comprehensive token data including current prices, historical prices, decimals, symbols, logos, and verification status.
Args: chain_id: Blockchain ID (required). Examples: "eth", "bsc", "polygon" token_id: Single token contract address (0x prefixed) token_ids: List of token addresses (max 100, 0x prefixed) date: Historical date in YYYY-MM-DD format for price lookup
Returns: Token object(s) with the following structure: { "id": "0xdac17f958d2ee523a2206206994597c13d831ec7", "chain": "eth", "name": "Tether USD", "symbol": "USDT", "price": 1.0, "decimals": 6, "logo_url": "https://...", "is_verified": true, "is_core": true }
Examples: - Get USDT: debank_get_token_info( chain_id="eth", token_id="0xdac17f958d2ee523a2206206994597c13d831ec7" ) - Get multiple tokens: debank_get_token_info( chain_id="eth", token_ids=["0xdac17f958d2ee523a2206206994597c13d831ec7", "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"] ) - Get historical price: debank_get_token_info( chain_id="eth", token_id="0xdac17f958d2ee523a2206206994597c13d831ec7", date="2024-01-15" )
Inputs: chain_id (required), date, token_id, token_ids. Returns: object
debank_get_user_approvalsA
Get user's token/NFT approvals and authorizations from DeBank.
Args: address: User's wallet address (required) chain_id: Blockchain ID (required) approval_type: "token" or "nft" (default: "token")
Returns: For tokens: Array of authorized tokens with spender info and exposure values For NFTs: Object with tokens, contracts, and total approved amounts
Security Note: This shows which contracts have permission to spend user's assets. High exposure values indicate security risk.
Examples: - Token approvals: debank_get_user_approvals(address="0x...", chain_id="eth") - NFT approvals: debank_get_user_approvals(address="0x...", chain_id="eth", approval_type="nft")
Inputs: address (required), chain_id (required), approval_type. Returns: object
debank_get_user_balanceA
Get user's total balance or chain-specific balance from DeBank.
This tool retrieves comprehensive portfolio data for a wallet address, including total balance across all chains or balance on a specific chain.
Args: address: User's wallet address (required, must start with 0x) chain_id: Optional chain ID. If provided, returns balance on that chain. If None, returns total balance across all chains. Examples: "eth", "bsc", "polygon", "arbitrum"
Returns: Balance information: - If chain_id is None: { "total_usd_value": 123456.78, "chain_list": [ { "id": "eth", "usd_value": 98765.43 }, ... ] } - If chain_id is specified: { "usd_value": 98765.43, "chain": "eth" }
Examples: - Get total balance: debank_get_user_balance( address="0x5853ed4f26a3fcea565b3fbc698bb19cdf6deb85" ) - Get Ethereum balance: debank_get_user_balance( address="0x5853ed4f26a3fcea565b3fbc698bb19cdf6deb85", chain_id="eth" ) - Get BSC balance: debank_get_user_balance( address="0x5853ed4f26a3fcea565b3fbc698bb19cdf6deb85", chain_id="bsc" )
Inputs: address (required), chain_id. Returns: object
debank_get_user_historyA
Get user's transaction history from DeBank.
Args: address: User's wallet address (required) chain_id: Optional chain ID. If None, returns history across all chains token_id: Optional filter by specific token start_time: Optional Unix timestamp to start from page_count: Number of transactions to return (default: 20)
Returns: Dictionary with: - history_list: Array of transaction objects - cate_dict: Transaction categories - project_dict: Involved projects/protocols - token_dict: Token metadata - cex_dict: CEX data if applicable
Examples: - Recent history: debank_get_user_history(address="0x...") - Ethereum only: debank_get_user_history(address="0x...", chain_id="eth") - USDT transactions: debank_get_user_history(address="0x...", chain_id="eth", token_id="0xdac17...")
Inputs: address (required), chain_id, token_id, page_count, +1 more. Returns: object
debank_get_user_net_curve_toolA
Get user's 24-hour asset value trends from DeBank.
Track portfolio performance over the last 24 hours with time-series data.
Args: address: User's wallet address (required, must start with 0x) chain_id: Optional single chain ID for chain-specific curve chain_ids: Optional comma-separated chain IDs for multi-chain aggregate
Returns: Time series data with summary statistics including start/end values, change amount, change percentage, and trend direction
Inputs: address (required), chain_id, chain_ids. Returns: object
debank_get_user_nftsA
Get user's NFT holdings from DeBank.
Args: address: User's wallet address (required) chain_id: Optional chain ID. If None, returns NFTs across all chains is_all: Include all NFTs (True) or only valuable ones (False, default) limit: Maximum number of NFTs to return (default: 50, max: 500) offset: Number of NFTs to skip for pagination (default: 0)
Returns: Dictionary with NFTs, metadata, content URLs, attributes, valuations, and pagination info
Examples: - All NFTs: debank_get_user_nfts(address="0x...") - NFTs on Ethereum: debank_get_user_nfts(address="0x...", chain_id="eth") - Paginated results: debank_get_user_nfts(address="0x...", limit=10, offset=0)
Inputs: address (required), limit, is_all, offset, +1 more. Returns: object
debank_get_user_protocolsA
Get user's DeFi protocol positions from DeBank.
Args: address: User's wallet address (required) protocol_id: Optional specific protocol ID chain_id: Optional chain ID. If None, returns positions across all chains detail_level: "simple" for balances only, "complex" for full position details (default: "complex")
Returns: Protocol positions with assets, debts, rewards, and portfolio items
Details: - "simple": Returns net_usd_value, asset_usd_value, debt_usd_value per protocol - "complex": Returns full PortfolioItemObject with supply tokens, borrow tokens, rewards, etc.
Examples: - All positions detailed: debank_get_user_protocols(address="0x...") - Simple balance summary: debank_get_user_protocols(address="0x...", detail_level="simple") - Specific protocol: debank_get_user_protocols(address="0x...", protocol_id="aave", chain_id="eth")
Inputs: address (required), chain_id, protocol_id, detail_level. Returns: object
debank_get_user_social_toolB
Get DeBank Connect social data (OAuth required - not yet implemented).
IMPORTANT: This tool requires OAuth implementation which is not yet available.
Args: access_token: OAuth bearer token (required) social_type: Type of social data - "profile", "followers", or "following" limit: Results per page (max 100, default 20) offset: Starting position (default 0)
Returns: Error message with list of available alternatives and future support details
Inputs: access_token (required), limit, offset, social_type. Returns: object
debank_get_user_tokensA
Get user's token holdings from DeBank.
Args: address: User's wallet address (required) chain_id: Optional chain ID. If None, returns tokens across all chains token_id: Optional specific token to query is_all: Include all tokens (True) or only valuable ones (False, default) limit: Maximum number of tokens to return (default: 50, max: 500) offset: Number of tokens to skip for pagination (default: 0)
Returns: Dictionary with token holdings, amounts, prices, USD values, and pagination info
Examples: - All tokens across chains: debank_get_user_tokens(address="0x...") - Tokens on Ethereum: debank_get_user_tokens(address="0x...", chain_id="eth") - Specific token balance: debank_get_user_tokens(address="0x...", chain_id="eth", token_id="0xdac17...") - Paginated results: debank_get_user_tokens(address="0x...", limit=10, offset=0)
Inputs: address (required), limit, is_all, offset, +2 more. Returns: object
debank_simulate_transaction_toolA
Pre-execute and explain a transaction using DeBank's simulation.
CRITICAL SAFETY TOOL: Always simulate transactions before sending to avoid costly mistakes and security issues.
Args: transaction_data: Transaction object with required fields (chainId, from, to, value, data) pending_transactions: Optional array of transactions to simulate first explain_only: If True, only explain the transaction without full simulation
Returns: Simulation results with safety analysis including risk level, warnings, recommendations, and estimated gas costs
Inputs: transaction_data (required), explain_only, pending_transactions. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 16 tools
Each tool targets a distinct resource or operation (e.g., chains, tokens, gas, pools, protocols, user data), and descriptions clearly differentiate them. No two tools appear to serve the same purpose.
Most tools follow a 'debank_get_<resource>' pattern, but some have a '_tool' suffix (e.g., debank_get_gas_prices_tool) while others do not (e.g., debank_get_chains). This inconsistency in suffix usage creates minor confusion.
16 tools is slightly above the typical 3-15 range for a focused server, but the scope (blockchain data, user portfolio, transaction simulation) justifies the count. It borders on heavy but remains manageable.
The server covers core DeBank functionalities: chains, tokens, pools, protocols, user balances, history, approvals, and transaction simulation. The only notable gap is the non-functional social tool, which is a minor dead end.
Maintenance
Related MCP Connectors
Query real-time blockchain token data across EVM and Solana networks. Access token balances, transfers, prices, holders, NFT ownership, DEX swaps, and liquidity pools. Supports Ethereum, Base, Arbitrum, BSC, Polygon, Solana, and more.
Multi-chain wallet intelligence: balances, transactions, ENS, OFAC screening across 7 chains.
Read-only on-chain intelligence for AI agents on Base: balances, tokens, gas, tx status.
Read-only on-chain intelligence for AI agents on Base: balances, tokens, gas, tx status.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables interaction with DeFi trading and portfolio analytics through Odos DEX aggregation and Zerion APIs. Provides access to swap quotes, liquidity operations, token pricing, portfolio analysis, and transaction history across multiple blockchain networks.3-
- AlicenseAqualityDmaintenanceEnables AI agents to retrieve real-time data on wallet DeFi positions, token balances, and NFT holdings across multiple blockchains. It supports hundreds of protocols and provides specialized tools for chain-specific or protocol-specific portfolio analysis.83MIT
- AlicenseAqualityFmaintenanceProvides access to DeFi Llama's free API for querying protocol TVL, chain TVL, yields, stablecoins, bridges, DEX volumes, and fees through natural language.814 npmMIT
- AlicenseAqualityCmaintenanceEnables AI agents to fetch live multi-chain portfolio, token info, gas prices, and token prices across Ethereum, Base, Polygon, Arbitrum, and Optimism with a single call. No API key required.4MIT