EVM MCP Server

Fornece serviços de blockchain para mais de 30 redes compatíveis com EVM através de uma interface unificada.

GitHub
379
Experimente este MCPPatrocinado

Documentação

EVM MCP Server

License: MIT EVM Networks TypeScript MCP Viem

Um servidor abrangente do Model Context Protocol (MCP) que fornece serviços de blockchain em mais de 60 redes compatíveis com EVM. Este servidor permite que agentes de IA interajam com Ethereum, Optimism, Arbitrum, Base, Polygon e muitas outras cadeias EVM com uma interface unificada por meio de 22 ferramentas e 10 prompts guiados por IA.

📋 Conteúdo

🔭 Visão geral

O MCP EVM Server utiliza o Model Context Protocol para fornecer serviços de blockchain a agentes de IA. Ele suporta uma ampla gama de serviços, incluindo:

  • Leitura do estado da blockchain (saldos, transações, blocos, etc.)
  • Interação com contratos inteligentes com busca automática de ABI em exploradores de blocos
  • Transferência de tokens (nativos, ERC20, ERC721, ERC1155)
  • Consulta de metadados e saldos de tokens
  • Serviços específicos por cadeia em mais de 60 redes EVM (34 mainnets + 26 testnets)
  • Resolução de nomes ENS para todos os parâmetros de endereço (use nomes legíveis como 'vitalik.eth' em vez de endereços)
  • Prompts amigáveis para IA que guiam agentes por fluxos de trabalho complexos

Todos os serviços são expostos por meio de uma interface consistente de ferramentas, recursos e prompts MCP, facilitando a descoberta e o uso da funcionalidade de blockchain por agentes de IA. Toda ferramenta que aceita endereços Ethereum também suporta nomes ENS, resolvendo-os automaticamente para endereços nos bastidores. O servidor inclui busca inteligente de ABI, eliminando a necessidade de conhecer as ABIs dos contratos com antecedência.

✨ Recursos

Acesso a dados da blockchain

  • Suporte a múltiplas cadeias para mais de 60 redes compatíveis com EVM (34 mainnets + 26 testnets)
  • Informações da cadeia, incluindo blockNumber, chainId e RPCs
  • Acesso a dados de blocos por número, hash ou mais recente
  • Detalhes de transações e recibos com logs decodificados
  • Saldos de endereços para tokens nativos e todos os padrões de token
  • Resolução ENS para endereços Ethereum legíveis (use 'vitalik.eth' em vez de '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045')

Serviços de tokens

  • Tokens ERC20

    • Obter metadados do token (nome, símbolo, decimais, fornecimento)
    • Verificar saldos de tokens
    • Transferir tokens entre endereços
    • Aprovar limites de gasto

  • NFTs (ERC721)

    • Obter metadados da coleção e do token
    • Verificar propriedade do token
    • Transferir NFTs entre endereços
    • Recuperar URIs de tokens e contar itens mantidos

  • Multi-tokens (ERC1155)

    • Obter saldos e metadados de tokens
    • Transferir tokens com quantidade
    • Acessar URIs de tokens

Interações com contratos inteligentes

  • Ler estado do contrato por meio de funções view/pure
  • Escrever em contratos — Executar qualquer função que altere o estado com busca automática de ABI
  • Verificação de contratos para distinguir de EOAs
  • Recuperação e filtragem de logs de eventos
  • Busca automática de ABI da API v2 do Etherscan em todas as 60+ redes (sem necessidade de conhecer ABIs com antecedência)
  • Análise e validação de ABI com descoberta de funções

Suporte abrangente a transações

  • Suporte flexível a carteiras — Configure com chave privada ou mnemônica (BIP-39) com suporte a caminho HD
  • Transferências de tokens nativos em todas as redes suportadas
  • Estimativa de gas para planejamento de transações
  • Status de transação e informações de recibo
  • Tratamento de erros com mensagens descritivas

Recursos de assinatura de mensagens

  • Assinatura de mensagens pessoais — Assine mensagens arbitrárias para autenticação e verificação
  • Assinatura de dados tipados EIP-712 — Assine dados estruturados para transações sem gas e meta-transações
  • Suporte a SIWE — Habilite fluxos de autenticação Sign-In With Ethereum
  • Assinaturas Permit — Crie aprovações off-chain para operações de tokens sem gas
  • Suporte a meta-transações — Assine dados de transação para serviços de relay e transferências sem gas

Fluxos de trabalho guiados por IA (Prompts)

  • Preparação de transações — Orientação para planejar e executar transferências
  • Análise de carteira — Ferramentas para analisar atividade e saldos da carteira
  • Exploração de contratos inteligentes — Busca interativa de ABI e análise de contratos
  • Interação com contratos — Execução segura de operações de escrita em contratos inteligentes
  • Informações de rede — Aprender sobre redes EVM e comparações
  • Auditoria de aprovações — Revisão e gerenciamento de aprovações de tokens
  • Diagnóstico de erros — Solução de problemas de falhas em transações

🌐 Redes suportadas

Mainnets

  • Ethereum (ETH)
  • Optimism (OP)
  • Arbitrum (ARB)
  • Arbitrum Nova
  • Base
  • Polygon (MATIC)
  • Polygon zkEVM
  • Avalanche (AVAX)
  • Binance Smart Chain (BSC)
  • zkSync Era
  • Linea
  • Celo
  • Gnosis (xDai)
  • Fantom (FTM)
  • Filecoin (FIL)
  • Moonbeam
  • Moonriver
  • Cronos
  • Scroll
  • Mantle
  • Manta
  • Blast
  • Fraxtal
  • Mode
  • Metis
  • Kroma
  • Zora
  • Aurora
  • Canto
  • Flow
  • Lumia

Testnets

  • Sepolia
  • Optimism Sepolia
  • Arbitrum Sepolia
  • Base Sepolia
  • Polygon Amoy
  • Avalanche Fuji
  • BSC Testnet
  • zkSync Sepolia
  • Linea Sepolia
  • Scroll Sepolia
  • Mantle Sepolia
  • Manta Sepolia
  • Blast Sepolia
  • Fraxtal Testnet
  • Mode Testnet
  • Metis Sepolia
  • Kroma Sepolia
  • Zora Sepolia
  • Celo Alfajores
  • Goerli
  • Holesky
  • Flow Testnet
  • Filecoin Calibration
  • Lumia Testnet

🛠️ Pré-requisitos

  • Bun 1.0.0 ou superior (recomendado)
  • Node.js 20.0.0 ou superior (se não estiver usando Bun)
  • Opcional: Chave de API do Etherscan para busca de ABI

📦 Instalação

# Clone the repository
git clone https://github.com/mcpdotdirect/evm-mcp-server.git
cd evm-mcp-server

# Install dependencies with Bun
bun install

# Or with npm
npm install

⚙️ Configuração

Variáveis de ambiente

O servidor usa as seguintes variáveis de ambiente. Para operações de escrita e busca de ABI, você deve configurar estas variáveis:

Configuração da carteira (para operações de escrita)

Você pode configurar sua carteira usando uma chave privada ou uma frase mnemônica:

Opção 1: Chave privada

export EVM_PRIVATE_KEY="0x..." # Your private key in hex format (with or without 0x prefix)

Opção 2: Frase mnemônica (recomendado para carteiras HD)

export EVM_MNEMONIC="word1 word2 word3 ... word12" # Your 12 or 24 word BIP-39 mnemonic
export EVM_ACCOUNT_INDEX="0" # Optional: Account index for HD wallet derivation (default: 0)

A opção mnemônica suporta derivação de carteira hierárquica determinística (HD):

  • Usa frases mnemônicas padrão BIP-39 (12 ou 24 palavras)
  • Suporta caminho de derivação BIP-44: m/44'/60'/0'/0/{accountIndex}
  • EVM_ACCOUNT_INDEX permite derivar diferentes contas da mesma mnemônica
  • O índice de conta padrão é 0 (primeira conta)

A carteira é usada para:

  • Transferir tokens nativos (ferramenta transfer_native)
  • Transferir tokens ERC20 (ferramenta transfer_erc20)
  • Aprovar gastos de tokens (ferramenta approve_token_spending)
  • Escrever em contratos inteligentes (ferramenta write_contract)
  • Assinar mensagens para autenticação (ferramenta sign_message)
  • Assinar dados estruturados para transações sem gas (ferramenta sign_typed_data)

⚠️ Segurança:

  • Nunca envie sua chave privada ou mnemônica para o controle de versão
  • Use variáveis de ambiente ou um sistema seguro de gerenciamento de chaves
  • Armazene mnemônicas com segurança — elas fornecem acesso a todas as contas derivadas
  • Considere usar diferentes índices de conta para diferentes finalidades

Chaves de API (para busca de ABI)

export ETHERSCAN_API_KEY="your-api-key-here"

Esta chave de API é opcional, mas necessária para:

  • Busca automática de ABI em exploradores de blocos (ferramenta get_contract_abi)
  • Busca automática de ABIs ao ler contratos (ferramenta read_contract com parâmetro abiJson)
  • O prompt fetch_and_analyze_abi

Obtenha sua chave de API gratuita em:

  • Etherscan — Para Ethereum e cadeias compatíveis
  • A mesma chave funciona em todas as 60+ redes EVM por meio da API v2 do Etherscan

Configuração do servidor

O servidor usa a seguinte configuração padrão:

  • Chain ID padrão: 1 (Ethereum Mainnet)
  • Porta do servidor: 3001
  • Host do servidor: 0.0.0.0 (acessível de qualquer interface de rede)

Esses valores estão codificados no aplicativo. Se você precisar modificá-los, pode editar os seguintes arquivos:

  • Para configuração da cadeia: src/core/chains.ts
  • Para configuração do servidor: src/server/http-server.ts

🚀 Uso

Usando npx (sem necessidade de instalação)

Você pode executar o MCP EVM Server diretamente sem instalação usando npx:

# Run the server in stdio mode (for CLI tools)
npx @mcpdotdirect/evm-mcp-server

# Run the server in HTTP mode (for web applications)
npx @mcpdotdirect/evm-mcp-server --http

Executando o servidor localmente

Inicie o servidor usando stdio (para incorporação em ferramentas CLI):

# Start the stdio server
bun start

# Development mode with auto-reload
bun dev

Ou inicie o servidor HTTP com SSE para aplicações web:

# Start the HTTP server
bun start:http

# Development mode with auto-reload
bun dev:http

Conectando-se ao servidor

Conecte-se a este servidor MCP usando qualquer cliente compatível com MCP. Para testes e depuração, você pode usar o MCP Inspector.

Conectando-se a partir do Cursor

Para conectar-se ao servidor MCP a partir do Cursor:

  1. Abra o Cursor e vá para Configurações (ícone de engrenagem no canto inferior esquerdo)

  2. Clique em "Features" na barra lateral esquerda

  3. Role para baixo até a seção "MCP Servers"

  4. Clique em "Add new MCP server"

  5. Insira os seguintes detalhes:

    • Nome do servidor: evm-mcp-server
    • Tipo: command
    • Comando: npx @mcpdotdirect/evm-mcp-server

  6. Clique em "Save"

Depois de conectado, você pode usar os recursos do servidor MCP diretamente no Cursor. O servidor aparecerá na lista de MCP Servers e poderá ser habilitado/desabilitado conforme necessário.

Usando mcp.json com o Cursor

Para uma configuração mais portátil que você pode compartilhar com sua equipe ou usar em vários projetos, você pode criar um arquivo .cursor/mcp.json no diretório raiz do seu projeto:

{
  "mcpServers": {
    "evm-mcp-server": {
      "command": "npx",
      "args": ["-y", "@mcpdotdirect/evm-mcp-server"]
    },
    "evm-mcp-http": {
      "command": "npx",
      "args": ["-y", "@mcpdotdirect/evm-mcp-server", "--http"]
    }
  }
}

Coloque este arquivo no diretório .cursor do seu projeto (crie-o se não existir), e o Cursor detectará e usará automaticamente essas configurações de servidor MCP ao trabalhar nesse projeto. Essa abordagem facilita:

  1. Compartilhar configurações MCP com sua equipe
  2. Controlar a versão da sua configuração MCP
  3. Usar diferentes configurações de servidor para diferentes projetos

Exemplo: Modo HTTP com SSE

Se você está desenvolvendo uma aplicação web e deseja conectar-se ao servidor HTTP com Server-Sent Events (SSE), você pode usar esta configuração:

{
  "mcpServers": {
    "evm-mcp-sse": {
      "url": "http://localhost:3001/sse"
    }
  }
}

Isso conecta diretamente ao endpoint SSE do servidor HTTP, o que é útil para:

  • Aplicações web que precisam se conectar ao servidor MCP a partir do navegador
  • Ambientes onde executar comandos locais não é ideal
  • Compartilhar uma única instância do servidor MCP entre vários usuários ou aplicações

Para usar esta configuração:

  1. Crie um diretório .cursor na raiz do seu projeto se ele não existir
  2. Salve o JSON acima como mcp.json no diretório .cursor
  3. Reinicie o Cursor ou abra seu projeto
  4. O Cursor detectará a configuração e oferecerá a ativação do(s) servidor(es)

Exemplo: Usando o MCP Server no Cursor

Após configurar o servidor MCP com mcp.json, você pode usá-lo facilmente no Cursor. Aqui está um exemplo de fluxo de trabalho:

  1. Crie um novo arquivo JavaScript/TypeScript no seu projeto:
// blockchain-example.js
async function main() {
  try {
    // Get ETH balance for an address using ENS
    console.log("Getting ETH balance for vitalik.eth...");

    // When using with Cursor, you can simply ask Cursor to:
    // "Check the ETH balance of vitalik.eth on mainnet"
    // Or "Transfer 0.1 ETH from my wallet to vitalik.eth"

    // Cursor will use the MCP server to execute these operations
    // without requiring any additional code from you

    // This is the power of the MCP integration - your AI assistant
    // can directly interact with blockchain data and operations
  } catch (error) {
    console.error("Error:", error.message);
  }
}

main();

  1. Com o arquivo aberto no Cursor, você pode pedir ao Cursor para:

    • "Verificar o saldo atual de ETH de vitalik.eth"
    • "Consultar o preço do USDC na Ethereum"
    • "Mostrar o bloco mais recente na Optimism"
    • "Verificar se 0x1234... é um endereço de contrato"

  2. O Cursor usará o servidor MCP para executar essas operações e retornará os resultados diretamente na sua conversa.

O servidor MCP lida com toda a comunicação com a blockchain, permitindo que o Cursor entenda e execute tarefas relacionadas a blockchain por meio de linguagem natural.

Conectando-se usando Claude CLI

Se você está usando o Claude CLI, pode conectar-se ao servidor MCP com apenas dois comandos:

# Add the MCP server
claude mcp add evm-mcp-server npx @mcpdotdirect/evm-mcp-server

# Start Claude with the MCP server enabled
claude

Exemplo: Obtendo um saldo de token com ENS

// Example of using the MCP client to check a token balance using ENS
const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("get-token-balance", {
  tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC on Ethereum
  ownerAddress: "vitalik.eth", // ENS name instead of address
  network: "ethereum",
});

console.log(result);
// {
//   tokenAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
//   owner: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
//   network: "ethereum",
//   raw: "1000000000",
//   formatted: "1000",
//   symbol: "USDC",
//   decimals: 6
// }

Exemplo: Resolvendo um nome ENS

// Example of using the MCP client to resolve an ENS name to an address
const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("resolve-ens", {
  ensName: "vitalik.eth",
  network: "ethereum",
});

console.log(result);
// {
//   ensName: "vitalik.eth",
//   normalizedName: "vitalik.eth",
//   resolvedAddress: "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045",
//   network: "ethereum"
// }

Exemplo: Executando múltiplas chamadas em lote com Multicall

// Example of using multicall to batch multiple contract reads in a single RPC call
const mcp = new McpClient("http://localhost:3000");

const result = await mcp.invokeTool("multicall", {
  network: "ethereum",
  calls: [
    {
      contractAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
      functionName: "balanceOf",
      args: ["0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"],
    },
    {
      contractAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
      functionName: "symbol",
    },
    {
      contractAddress: "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48", // USDC
      functionName: "decimals",
    },
  ],
});

console.log(result);
// {
//   network: "ethereum",
//   totalCalls: 3,
//   successfulCalls: 3,
//   failedCalls: 0,
//   results: [
//     { contractAddress: "0xA0b...", functionName: "balanceOf", result: "1000000000", status: "success" },
//     { contractAddress: "0xA0b...", functionName: "symbol", result: "USDC", status: "success" },
//     { contractAddress: "0xA0b...", functionName: "decimals", result: "6", status: "success" }
//   ]
// }

📚 Referência da API

Ferramentas

O servidor fornece 25 ferramentas MCP focadas para agentes. Todas as ferramentas que aceitam parâmetros de endereço suportam tanto endereços Ethereum quanto nomes ENS.

Informações da carteira

Nome da FerramentaDescriçãoParâmetros Chave
get_wallet_addressObter o endereço da carteira configurada (a partir de EVM_PRIVATE_KEY)nenhum

Informações de Rede

Nome da FerramentaDescriçãoParâmetros Chave
get_chain_infoObter informações de redenetwork
get_supported_networksListar todas as redes EVM suportadasnenhum
get_gas_priceObter preços atuais de gás em uma redenetwork

Serviços ENS

Nome da FerramentaDescriçãoParâmetros Chave
resolve_ens_nameResolver nome ENS para endereçoensName, network
lookup_ens_addressPesquisa reversa de endereço para nome ENSaddress, network

Informações de Bloco e Transação

Nome da FerramentaDescriçãoParâmetros Chave
get_blockObter dados do blocoblockNumber ou blockHash, network
get_latest_blockObter dados do bloco mais recentenetwork
get_transactionObter detalhes da transaçãotxHash, network
get_transaction_receiptObter recibo de transação com logstxHash, network
wait_for_transactionAguardar confirmação da transaçãotxHash, confirmations, network

Informações de Saldo e Token

Nome da FerramentaDescriçãoParâmetros Chave
get_balanceObter saldo de token nativoaddress (endereço/ENS), network
get_token_balanceVerificar saldo de token ERC20tokenAddress (endereço/ENS), ownerAddress (endereço/ENS), network
get_allowanceVerificar permissão de gasto de tokentokenAddress (endereço/ENS), ownerAddress (endereço/ENS), spenderAddress (endereço/ENS), network

Interações com Contratos Inteligentes

Nome da FerramentaDescriçãoParâmetros Chave
get_contract_abiBuscar ABI do contrato no explorador de blocos (mais de 60 redes)contractAddress (endereço/ENS), network
read_contractLer estado do contrato inteligente (busca ABI automaticamente se necessário)contractAddress, functionName, args[], abiJson (opcional), network
write_contractExecutar funções que alteram o estado (busca ABI automaticamente se necessário)contractAddress, functionName, args[], value (opcional), abiJson (opcional), network
multicallAgrupar múltiplas chamadas de leitura em uma única solicitação RPC (usa Multicall3)calls[] (matriz de chamadas de contrato), allowFailure (opcional), network

Transferências de Token

Nome da FerramentaDescriçãoParâmetros Chave
transfer_nativeEnviar tokens nativos (ETH, etc.)to (endereço/ENS), amount, network
transfer_erc20Transferir tokens ERC20tokenAddress (endereço/ENS), to (endereço/ENS), amount, network
approve_token_spendingAprovar permissões de tokentokenAddress (endereço/ENS), spenderAddress (endereço/ENS), amount, network

Serviços NFT

Nome da FerramentaDescriçãoParâmetros Chave
get_nft_infoObter metadados de NFT (ERC721)tokenAddress (endereço/ENS), tokenId, network
get_erc1155_balanceVerificar saldo ERC1155tokenAddress (endereço/ENS), tokenId, ownerAddress (endereço/ENS), network

Assinatura de Mensagens

Nome da FerramentaDescriçãoParâmetros Chave
sign_messageAssinar mensagens arbitrárias para autenticação e verificação (SIWE, assinaturas off-chain)message
sign_typed_dataAssinar dados estruturados EIP-712 para transações sem gás, permissões e meta-transaçõesdomainJson, typesJson, primaryType, messageJson

Recursos

O servidor expõe dados de blockchain através dos seguintes URIs de recursos MCP. Todos os URIs de recursos que aceitam endereços também suportam nomes ENS, que são automaticamente resolvidos para endereços.

Recursos de Blockchain

Padrão de URI de RecursoDescrição
evm://{network}/chainInformações da cadeia para uma rede específica
evm://chainInformações da cadeia principal Ethereum
evm://{network}/block/{blockNumber}Dados do bloco por número
evm://{network}/block/latestDados do bloco mais recente
evm://{network}/address/{address}/balanceSaldo de token nativo
evm://{network}/tx/{txHash}Detalhes da transação
evm://{network}/tx/{txHash}/receiptRecibo de transação com logs

Recursos de Token

Padrão de URI de RecursoDescrição
evm://{network}/token/{tokenAddress}Informações de token ERC20
evm://{network}/token/{tokenAddress}/balanceOf/{address}Saldo de token ERC20
evm://{network}/nft/{tokenAddress}/{tokenId}Informações de token NFT (ERC721)
evm://{network}/nft/{tokenAddress}/{tokenId}/isOwnedBy/{address}Verificação de propriedade de NFT
evm://{network}/erc1155/{tokenAddress}/{tokenId}/uriURI de token ERC1155
evm://{network}/erc1155/{tokenAddress}/{tokenId}/balanceOf/{address}Saldo de token ERC1155

🔒 Considerações de Segurança

  • Chaves privadas são usadas apenas para assinatura de transações e nunca são armazenadas pelo servidor
  • Considere implementar mecanismos adicionais de autenticação para uso em produção
  • Use HTTPS para o servidor HTTP em ambientes de produção
  • Implemente limitação de taxa para prevenir abuso
  • Para serviços de alto valor, considere adicionar etapas de confirmação

📁 Estrutura do Projeto

mcp-evm-server/
├── src/
│   ├── index.ts                # Main stdio server entry point
│   ├── server/                 # Server-related files
│   │   ├── http-server.ts      # HTTP server with SSE
│   │   └── server.ts           # General server setup
│   ├── core/
│   │   ├── chains.ts           # Chain definitions and utilities
│   │   ├── resources.ts        # MCP resources implementation
│   │   ├── tools.ts            # MCP tools implementation
│   │   ├── prompts.ts          # MCP prompts implementation
│   │   └── services/           # Core blockchain services
│   │       ├── index.ts        # Operation exports
│   │       ├── balance.ts      # Balance services
│   │       ├── transfer.ts     # Token transfer services
│   │       ├── utils.ts        # Utility functions
│   │       ├── tokens.ts       # Token metadata services
│   │       ├── contracts.ts    # Contract interactions
│   │       ├── transactions.ts # Transaction services
│   │       └── blocks.ts       # Block services
│   │       └── clients.ts      # RPC client utilities
├── package.json
├── tsconfig.json
└── README.md

🛠️ Desenvolvimento

Para modificar ou estender o servidor:

  1. Adicione novos serviços no arquivo apropriado em src/core/services/
  2. Registre novas ferramentas em src/core/tools.ts
  3. Registre novos recursos em src/core/resources.ts
  4. Adicione suporte a novas redes em src/core/chains.ts
  5. Para alterar a configuração do servidor, edite os valores codificados em src/server/http-server.ts

📄 Licença

Este projeto é licenciado sob os termos da Licença MIT.