Skip to main content
Glama

DeBank MCP Server

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

Python 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!

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

  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
  1. 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"
      }
    }
  }
}
  1. Substitua /caminho/para/debank-mcp-server pelo caminho real

  2. Substitua sua_api_key_aqui pela sua API key do DeBank

  3. Reinicie o Claude Desktop

Windows

  1. Edite o arquivo de configuração:

notepad %APPDATA%\Claude\claude_desktop_config.json
  1. 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
  1. 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

⭐ 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 tools
debank_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

    A3.9/5.0

    Scored across 16 tools

    Disambiguation5/5

    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.

    Naming Consistency3/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables 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
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      8
      3
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      4
      MIT