evm-mcp

Um servidor MCP que fornece acesso completo aos métodos JSON-RPC da Máquina Virtual Ethereum (EVM). Funciona com qualquer provedor de nó compatível com EVM, incluindo Infura, Alchemy, QuickNode, nós locais e outros.

GitHub

Experimente este MCPPatrocinado

Documentação

⛽ Servidor EVM MCP

Acesso completo a EVM JSON-RPC no seu fluxo de trabalho com IA. Consulte qualquer rede compatível com EVM (Ethereum, Polygon, Arbitrum, Optimism, BSC e outras) por meio de qualquer provedor de nó. Funciona com Infura, Alchemy, QuickNode, nós locais e muito mais.

Um servidor MCP (Model Context Protocol) que fornece acesso abrangente aos métodos JSON-RPC da Ethereum Virtual Machine (EVM) para ambientes de codificação com IA, como Cursor e Claude Desktop.

Por que usar o EVM MCP?

🌐 Qualquer rede EVM – Ethereum, Polygon, Arbitrum, Optimism, BSC, Avalanche e outras
🔌 Qualquer provedor de nó – Infura, Alchemy, QuickNode, nós locais ou RPC personalizado
📊 Mais de 20 métodos RPC – Acesso completo a dados de blockchain, transações e contratos
⚡ Configuração fácil – Instalação com um clique no Cursor ou configuração manual simples
🔧 Configuração flexível – Funciona com qualquer endpoint compatível com JSON-RPC

Início Rápido

Pronto para interagir com blockchains EVM? Instale em segundos:

Instalar no Cursor (Recomendado):

🔗 Instalar no Cursor

Ou instale manualmente:

npm install -g @jamesanz/evm-mcp
# Or from source:
git clone https://github.com/JamesANZ/evm-mcp.git
cd evm-mcp && npm install && npm run build

Recursos

🔢 Dados de Blockchain

eth_blockNumber – Obter o número do bloco mais recente
eth_getBalance – Obter saldo de conta
eth_getTransactionCount – Obter contagem de transações (nonce)
eth_getBlockByNumber – Obter informações do bloco
eth_getTransactionByHash – Obter detalhes da transação
eth_getTransactionReceipt – Obter recibo da transação
eth_getCode – Obter bytecode do contrato
eth_getStorageAt – Obter valor de armazenamento

🔄 Transações

eth_call – Executar chamada de contrato
eth_estimateGas – Estimar gás para transação
eth_sendRawTransaction – Enviar transação assinada
eth_gasPrice – Obter preço atual do gás

🧪 Simulação de Transações (somente leitura, nunca transmite)

Crie transações em linguagem natural e simule-as contra o estado EVM com fork/sobrescrito. Informa se uma transação teria sucesso ou reverteria, o motivo da reversão em linguagem simples, o gás estimado e as alterações de saldo/estado. Suporta aliases de endereço e nomes ENS (ex.: alice.eth). Por padrão, o remetente recebe ETH virtual para que uma simulação possa ser executada "de" qualquer endereço; defina fund: false para usar saldos reais.

simulate_native_transfer – Simular envio de moeda nativa (ex.: "Transferir 100 ETH de A para B")
simulate_erc20_transfer – Simular uma transferência ERC20 com valores legíveis (ex.: "Transferir 10 USDC para alice.eth de fun.eth")
simulate_contract_call – Codificar uma assinatura de função + argumentos e simular a chamada
simulate_transaction – Simular uma transação bruta (de/para/valor/dados)
encode_function_data – Codificar calldata a partir de uma assinatura legível (utilitário puro, sem RPC)

Essas ferramentas usam apenas eth_call, eth_estimateGas e debug_traceCall (quando o provedor suporta). Elas nunca assinam ou enviam uma transação real. Diffs de estado reais são usados quando debug_traceCall está disponível; caso contrário, as alterações são inferidas da intenção decodificada.

📊 Eventos e Logs

eth_getLogs – Obter logs de eventos

🌍 Rede

list_supported_networks – Listar redes e provedores configurados
list_known_addresses – Listar aliases de carteiras configurados e endereços de tokens/contratos conhecidos
eth_chainId – Obter ID da chain
net_version – Obter versão da rede
net_listening – Verificar se está escutando
net_peerCount – Obter contagem de pares

🌐 Web3

web3_clientVersion – Obter versão do cliente
web3_sha3 – Aplicar hash a dados com Keccak-256

Instalação

Cursor (Um Clique)

Clique no link de instalação acima ou use:

cursor://anysphere.cursor-deeplink/mcp/install?name=evm-mcp&config=eyJldm0tbWNwIjp7ImNvbW1hbmQiOiJucHgiLCJhcmdzIjpbIi15IiwiQGphbWVzYW56L2V2bS1tY3AiXX19

Instalação Manual

Requisitos: Node.js 18+ e npm

# Clone and build
git clone https://github.com/JamesANZ/evm-mcp.git
cd evm-mcp
npm install
npm run build

# Set provider API keys
export INFURA_API_KEY="your-infura-api-key"
export DEFAULT_NETWORK="ethereum"
export DEFAULT_PROVIDER="infura"

# Run server
npm start

Claude Desktop

Adicione em claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "evm-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/evm-mcp/build/index.js"],
      "env": {
        "INFURA_API_KEY": "your-infura-api-key",
        "DEFAULT_NETWORK": "ethereum",
        "DEFAULT_PROVIDER": "infura",
        "RPC_PROVIDER_ORDER": "infura,alchemy"
      }
    }
  }
}

Reinicie o Claude Desktop após a configuração.

Configuração

Variáveis de Ambiente

Variável	Obrigatória	Descrição
`INFURA_API_KEY`	Uma de*	Chave de API do projeto Infura (predefinição integrada)
`ALCHEMY_API_KEY`	Uma de*	Chave de API do app Alchemy (predefinição integrada)
`DEFAULT_NETWORK`	Não	Slug da chain padrão ou ID da chain (padrão: `ethereum`)
`DEFAULT_PROVIDER`	Não	Slug do provedor a preferir (`infura`, `alchemy` ou personalizado)
`RPC_PROVIDER_ORDER`	Não	Ordem de fallback de provedores separada por vírgulas (padrão: `infura,alchemy`)
`CUSTOM_PROVIDERS`	Uma de*	Matriz JSON de provedores definidos pelo usuário
`CUSTOM_NETWORKS`	Uma de*	Matriz JSON de redes definidas pelo usuário
`KNOWN_ADDRESSES`	Não	Matriz JSON de tokens/contratos conhecidos (com escopo por rede)
`WALLET_ADDRESSES`	Não	Matriz JSON de aliases pessoais de carteiras e contratos

*É necessária pelo menos uma chave de API de provedor, um provedor personalizado ou uma rede personalizada com rpcUrl.

Provedores Integrados (Infura / Alchemy)

Defina uma chave de API e o servidor constrói as URLs RPC automaticamente para as redes suportadas:

{
  "INFURA_API_KEY": "your-infura-key",
  "DEFAULT_NETWORK": "ethereum",
  "DEFAULT_PROVIDER": "infura",
  "RPC_PROVIDER_ORDER": "infura,alchemy"
}

Cada ferramenta RPC aceita um parâmetro opcional network (slug, nome ou ID da chain). Quando omitido, DEFAULT_NETWORK é usado.

{
  "tool": "eth_chainId",
  "arguments": { "network": "polygon" }
}

Use list_supported_networks para descobrir redes e provedores configurados.

Provedores Personalizados (`CUSTOM_PROVIDERS`)

Registre qualquer provedor RPC fornecendo um modelo de URL base e URLs específicas por rede:

"CUSTOM_PROVIDERS": "[{\"slug\":\"quicknode\",\"apiKeyEnv\":\"QUICKNODE_API_KEY\",\"baseUrl\":\"https://rpc.example.com/v1/{apiKey}\",\"networkUrls\":{\"ethereum\":\"https://eth.quiknode.pro/{apiKey}/\",\"polygon\":\"https://polygon.quiknode.pro/{apiKey}/\"}}]"

Valores networkUrls absolutos são usados diretamente (com substituição de {apiKey}).
Caminhos relativos (começando com /) são anexados a baseUrl.

Redes Personalizadas (`CUSTOM_NETWORKS`)

Registre chains arbitrárias por nome:

"CUSTOM_NETWORKS": "[{\"name\":\"HyperEVM\",\"slug\":\"hyperevm\",\"chainId\":999,\"rpcUrl\":\"https://rpc.hyperliquid.xyz/evm\"}]"

Ou roteie por um provedor definindo provider e adicionando o slug da rede ao networkUrls desse provedor.

Endereços Conhecidos (`KNOWN_ADDRESSES`)

Registre tokens e contratos por nome para que as ferramentas aceitem aliases como USDC em vez de endereços hex brutos. Cada entrada tem escopo por rede:

"KNOWN_ADDRESSES": "[{\"name\":\"USDC\",\"address\":\"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48\",\"network\":\"ethereum\",\"type\":\"token\",\"decimals\":6,\"aliases\":[\"usd-coin\"]}]"

Campo	Obrigatório	Descrição
`name`	sim	Chave de consulta principal
`address`	sim	Endereço do contrato com checksum
`network`	sim	Slug da chain, nome, ID da chain ou alias de rede
`type`	não	`token` ou `contract` (padrão: `contract`)
`decimals`	não	Decimais do token para saldos formatados
`aliases`	não	Chaves de consulta extras

Quando eth_getBalance é chamado com um alias de token, o servidor usa a primeira carteira configurada em WALLET_ADDRESSES como detentora do token.

Endereços de Carteira (`WALLET_ADDRESSES`)

Registre carteiras pessoais e contratos por alias para que você possa dizer "verificar minha carteira pessoal" em vez de colar o hex:

"WALLET_ADDRESSES": "[{\"name\":\"my-wallet\",\"address\":\"0x42ea529282DDE0AA87B42d9E83316eb23FE62c3f\",\"aliases\":[\"personal\",\"my wallet\"],\"description\":\"Main EOA\"}]"

Campo	Obrigatório	Descrição
`name`	sim	Chave de consulta principal
`address`	sim	Endereço da carteira ou contrato
`network`	não	Limitar o alias a uma chain (padrão: todas as chains)
`aliases`	não	Chaves de consulta extras
`description`	não	Nota legível

Aliases de endereço funcionam em eth_getBalance, eth_getCode, eth_call, eth_getLogs e outras ferramentas que aceitam parâmetros de endereço. Use list_known_addresses para descobrir aliases configurados.

Migração do RPC_URL

- "RPC_URL": "https://mainnet.infura.io/v3/KEY"
- "CHAIN_ID": "1"
+ "INFURA_API_KEY": "KEY"
+ "DEFAULT_NETWORK": "ethereum"
+ "DEFAULT_PROVIDER": "infura"

Alterações de configuração exigem reiniciar o servidor MCP.

Redes Integradas Suportadas

Ethereum: Mainnet, Sepolia
Polygon: Mainnet, Amoy
Arbitrum: One, Sepolia
Optimism: Mainnet, Sepolia
BNB Smart Chain: Mainnet, Testnet
Avalanche: C-Chain
Base: Mainnet, Sepolia
Qualquer chain compatível com EVM via CUSTOM_NETWORKS

Exemplos de Uso

Obter o Número do Bloco Mais Recente

Consulte o número do bloco atual:

{
  "tool": "eth_blockNumber",
  "arguments": {}
}

Obter Saldo de Conta

Verifique o saldo de um endereço usando um endereço hex ou alias configurado:

{
  "tool": "eth_getBalance",
  "arguments": {
    "address": "personal",
    "blockNumber": "latest"
  }
}

Obter Detalhes da Transação

Visualize informações da transação:

{
  "tool": "eth_getTransactionByHash",
  "arguments": {
    "txHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
  }
}

Chamar Contrato Inteligente

Execute uma chamada de contrato:

{
  "tool": "eth_call",
  "arguments": {
    "to": "0xA0b86a33E6441c8C06DDD46C310c0eF8D9441C8F",
    "data": "0x70a08231000000000000000000000000742d35Cc6634C0532925a3b8D6Ac6e2F0C4C9B7C"
  }
}

Obter Logs de Eventos

Consulte eventos de contrato:

{
  "tool": "eth_getLogs",
  "arguments": {
    "fromBlock": "0x1234567",
    "toBlock": "latest",
    "address": "0xA0b86a33E6441c8C06DDD46C310c0eF8D9441C8F",
    "topics": [
      "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef"
    ]
  }
}

Casos de Uso

Análise de Blockchain – Consulte dados de transações, saldos e estados de contratos
Aplicações DeFi – Monitore saldos de tokens, recibos de transações e chamadas de contratos inteligentes
Projetos NFT – Acompanhe transferências, metadados e estatísticas de coleções
Ferramentas de Desenvolvimento – Depure transações, estime gás e teste contratos inteligentes
Monitoramento – Observe eventos específicos e padrões de transações
Pesquisa – Analise dados de blockchain em múltiplas redes EVM

Detalhes Técnicos

Construído com: Node.js, TypeScript, MCP SDK, Ethers.js
Dependências: @modelcontextprotocol/sdk, ethers, zod
Plataformas: macOS, Windows, Linux

Variáveis de Ambiente: Consulte Configuração acima.

Contribuindo

⭐ Se este projeto ajudar você, dê uma estrela no GitHub! ⭐

Contribuições são bem-vindas! Abra uma issue ou envie um pull request.

Licença

Licença MIT – consulte LICENSE.md para detalhes.

Suporte

Se você achar este projeto útil, considere apoiá-lo:

⚡ Lightning Network

lnbc1pjhhsqepp5mjgwnvg0z53shm22hfe9us289lnaqkwv8rn2s0rtekg5vvj56xnqdqqcqzzsxqyz5vqsp5gu6vh9hyp94c7t3tkpqrp2r059t4vrw7ps78a4n0a2u52678c7yq9qyyssq7zcferywka50wcy75skjfrdrk930cuyx24rg55cwfuzxs49rc9c53mpz6zug5y2544pt8y9jflnq0ltlha26ed846jh0y7n4gm8jd3qqaautqa

₿ Bitcoin: bc1ptzvr93pn959xq4et6sqzpfnkk2args22ewv5u2th4ps7hshfaqrshe0xtp

Ξ Ethereum/EVM: 0x42ea529282DDE0AA87B42d9E83316eb23FE62c3f