EVM MCP Server

Proporciona servicios blockchain para más de 30 redes compatibles con EVM a través de una interfaz unificada.

Documentación

Servidor MCP EVM

Un servidor integral del Protocolo de Contexto de Modelos (MCP) que proporciona servicios blockchain en más de 60 redes compatibles con EVM. Este servidor permite a los agentes de IA interactuar con Ethereum, Optimism, Arbitrum, Base, Polygon y muchas otras cadenas EVM con una interfaz unificada a través de 22 herramientas y 10 indicaciones guiadas por IA.

📋 Contenido

Descripción general
Características
Redes compatibles
Requisitos previos
Instalación
Configuración
- Variables de entorno
- Configuración del servidor
Uso
Referencia de la API
Consideraciones de seguridad
Estructura del proyecto
Desarrollo
Licencia

🔭 Descripción general

El servidor MCP EVM aprovecha el Protocolo de Contexto de Modelos para proporcionar servicios blockchain a los agentes de IA. Admite una amplia gama de servicios, entre ellos:

Lectura del estado de la blockchain (saldos, transacciones, bloques, etc.)
Interacción con contratos inteligentes con obtención automática de ABI desde exploradores de bloques
Transferencia de tokens (nativos, ERC20, ERC721, ERC1155)
Consulta de metadatos y saldos de tokens
Servicios específicos por cadena en más de 60 redes EVM (34 mainnets + 26 testnets)
Resolución de nombres ENS para todos los parámetros de direcciones (use nombres legibles como 'vitalik.eth' en lugar de direcciones)
Indicaciones amigables para IA que guían a los agentes a través de flujos de trabajo complejos

Todos los servicios se exponen a través de una interfaz coherente de herramientas, recursos e indicaciones de MCP, lo que facilita que los agentes de IA descubran y utilicen la funcionalidad blockchain. Cada herramienta que acepta direcciones de Ethereum también admite nombres ENS, resolviéndolos automáticamente a direcciones en segundo plano. El servidor incluye obtención inteligente de ABI, eliminando la necesidad de conocer los ABI de los contratos de antemano.

✨ Características

Acceso a datos de la blockchain

Soporte multicadena para más de 60 redes compatibles con EVM (34 mainnets + 26 testnets)
Información de la cadena que incluye blockNumber, chainId y RPC
Datos de bloques accesibles por número, hash o el más reciente
Detalles de transacciones y recibos con registros decodificados
Saldos de direcciones para tokens nativos y todos los estándares de tokens
Resolución ENS para direcciones de Ethereum legibles (use 'vitalik.eth' en lugar de '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045')

Servicios de tokens

Tokens ERC20
- Obtener metadatos del token (nombre, símbolo, decimales, suministro)
- Consultar saldos de tokens
- Transferir tokens entre direcciones
- Aprobar límites de gasto
NFT (ERC721)
- Obtener metadatos de colección y de token
- Verificar propiedad de tokens
- Transferir NFT entre direcciones
- Recuperar URI de tokens y contar tenencias
Multi-tokens (ERC1155)
- Obtener saldos y metadatos de tokens
- Transferir tokens con cantidad
- Acceder a URI de tokens

Interacciones con contratos inteligentes

Leer estado del contrato a través de funciones view/pure
Escribir en contratos: ejecutar cualquier función que cambie el estado con obtención automática de ABI
Verificación de contratos para distinguirlos de EOA
Registros de eventos: recuperación y filtrado
Obtención automática de ABI desde la API v2 de Etherscan en las más de 60 redes (sin necesidad de conocer los ABI de antemano)
Análisis y validación de ABI con descubrimiento de funciones

Soporte integral de transacciones

Soporte de billetera flexible: configurable con clave privada o frase mnemotécnica (BIP-39) con soporte de ruta HD
Transferencias de tokens nativos en todas las redes compatibles
Estimación de gas para la planificación de transacciones
Estado de transacciones e información de recibos
Manejo de errores con mensajes descriptivos

Capacidades de firma de mensajes

Firma de mensajes personales: firme mensajes arbitrarios para autenticación y verificación
Firma de datos tipados EIP-712: firme datos estructurados para transacciones sin gas y meta-transacciones
Soporte SIWE: habilite flujos de autenticación de Inicio de Sesión con Ethereum
Firmas de permiso: cree aprobaciones fuera de la cadena para operaciones de tokens sin gas
Soporte de meta-transacciones: firme datos de transacciones para servicios de relevo y transferencias sin gas

Flujos de trabajo guiados por IA (Indicaciones)

Preparación de transacciones: orientación para planificar y ejecutar transferencias
Análisis de billeteras: herramientas para analizar la actividad y las tenencias de una billetera
Exploración de contratos inteligentes: obtención interactiva de ABI y análisis de contratos
Interacción con contratos: ejecución segura de operaciones de escritura en contratos inteligentes
Información de redes: aprendizaje sobre redes EVM y comparaciones
Auditoría de aprobaciones: revisión y gestión de aprobaciones de tokens
Diagnóstico de errores: solución de problemas de fallos en transacciones

🌐 Redes compatibles

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

🛠️ Requisitos previos

Bun 1.0.0 o superior (recomendado)
Node.js 20.0.0 o superior (si no usa Bun)
Opcional: clave de API de Etherscan para la obtención de ABI

📦 Instalación

# 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

⚙️ Configuración

Variables de entorno

El servidor utiliza las siguientes variables de entorno. Para operaciones de escritura y obtención de ABI, debe configurar estas variables:

Configuración de la billetera (para operaciones de escritura)

Puede configurar su billetera usando una clave privada o una frase mnemotécnica:

Opción 1: Clave privada

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

Opción 2: Frase mnemotécnica (recomendada para billeteras 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)

La opción de frase mnemotécnica admite la derivación de billeteras deterministas jerárquicas (HD):

Usa frases mnemotécnicas estándar BIP-39 (12 o 24 palabras)
Admite la ruta de derivación BIP-44: m/44'/60'/0'/0/{accountIndex}
EVM_ACCOUNT_INDEX le permite derivar diferentes cuentas de la misma frase mnemotécnica
El índice de cuenta predeterminado es 0 (primera cuenta)

La billetera se usa para:

Transferir tokens nativos (herramienta transfer_native)
Transferir tokens ERC20 (herramienta transfer_erc20)
Aprobar gastos de tokens (herramienta approve_token_spending)
Escribir en contratos inteligentes (herramienta write_contract)
Firmar mensajes para autenticación (herramienta sign_message)
Firmar datos estructurados para transacciones sin gas (herramienta sign_typed_data)

⚠️ Seguridad:

Nunca confirme su clave privada o frase mnemotécnica en el control de versiones
Use variables de entorno o un sistema seguro de gestión de claves
Almacene las frases mnemotécnicas de forma segura: brindan acceso a todas las cuentas derivadas
Considere usar diferentes índices de cuenta para diferentes propósitos

Claves de API (para la obtención de ABI)

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

Esta clave de API es opcional pero necesaria para:

Obtención automática de ABI desde exploradores de bloques (herramienta get_contract_abi)
Obtención automática de ABI al leer contratos (herramienta read_contract con el parámetro abiJson)
La indicación fetch_and_analyze_abi

Obtenga su clave de API gratuita en:

Etherscan: para Ethereum y cadenas compatibles
La misma clave funciona en las más de 60 redes EVM a través de la API v2 de Etherscan

Configuración del servidor

El servidor usa la siguiente configuración predeterminada:

ID de cadena predeterminado: 1 (Ethereum Mainnet)
Puerto del servidor: 3001
Host del servidor: 0.0.0.0 (accesible desde cualquier interfaz de red)

Estos valores están codificados en la aplicación. Si necesita modificarlos, puede editar los siguientes archivos:

Para la configuración de la cadena: src/core/chains.ts
Para la configuración del servidor: src/server/http-server.ts

🚀 Uso

Uso con npx (sin necesidad de instalación)

Puede ejecutar el servidor MCP EVM directamente sin instalación 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

Ejecutar el servidor localmente

Inicie el servidor usando stdio (para incrustarlo en herramientas CLI):

# Start the stdio server
bun start

# Development mode with auto-reload
bun dev

O inicie el servidor HTTP con SSE para aplicaciones web:

# Start the HTTP server
bun start:http

# Development mode with auto-reload
bun dev:http

Conexión al servidor

Conéctese a este servidor MCP usando cualquier cliente compatible con MCP. Para pruebas y depuración, puede usar el Inspector MCP.

Conexión desde Cursor

Para conectarse al servidor MCP desde Cursor:

Abra Cursor y vaya a Configuración (ícono de engranaje en la parte inferior izquierda)
Haga clic en "Features" en la barra lateral izquierda
Desplácese hacia abajo hasta la sección "MCP Servers"
Haga clic en "Add new MCP server"
Ingrese los siguientes detalles:
- Nombre del servidor: evm-mcp-server
- Tipo: command
- Comando: npx @mcpdotdirect/evm-mcp-server
Haga clic en "Save"

Una vez conectado, puede usar las capacidades del servidor MCP directamente dentro de Cursor. El servidor aparecerá en la lista de servidores MCP y se puede habilitar/deshabilitar según sea necesario.

Uso de mcp.json con Cursor

Para una configuración más portátil que pueda compartir con su equipo o usar en varios proyectos, puede crear un archivo .cursor/mcp.json en el directorio raíz de su proyecto:

{
  "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 archivo en el directorio .cursor de su proyecto (créelo si no existe), y Cursor detectará y usará automáticamente estas configuraciones de servidor MCP cuando trabaje en ese proyecto. Este enfoque facilita:

Compartir configuraciones de MCP con su equipo
Control de versiones de su configuración de MCP
Usar diferentes configuraciones de servidor para diferentes proyectos

Ejemplo: modo HTTP con SSE

Si está desarrollando una aplicación web y desea conectarse al servidor HTTP con Eventos Enviados por el Servidor (SSE), puede usar esta configuración:

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

Esto se conecta directamente al endpoint SSE del servidor HTTP, lo cual es útil para:

Aplicaciones web que necesitan conectarse al servidor MCP desde el navegador
Entornos donde ejecutar comandos locales no es ideal
Compartir una única instancia del servidor MCP entre múltiples usuarios o aplicaciones

Para usar esta configuración:

Cree un directorio .cursor en la raíz de su proyecto si no existe
Guarde el JSON anterior como mcp.json en el directorio .cursor
Reinicie Cursor o abra su proyecto
Cursor detectará la configuración y ofrecerá habilitar los servidores

Ejemplo: uso del servidor MCP en Cursor

Después de configurar el servidor MCP con mcp.json, puede usarlo fácilmente en Cursor. Aquí hay un flujo de trabajo de ejemplo:

Cree un nuevo archivo JavaScript/TypeScript en su proyecto:

// 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();

Con el archivo abierto en Cursor, puede pedirle a Cursor que:
- "Consulte el saldo actual de ETH de vitalik.eth"
- "Busque el precio de USDC en Ethereum"
- "Muéstreme el último bloque en Optimism"
- "Verifique si 0x1234... es una dirección de contrato"
Cursor usará el servidor MCP para ejecutar estas operaciones y devolverá los resultados directamente en su conversación.

El servidor MCP maneja toda la comunicación blockchain mientras permite que Cursor comprenda y ejecute tareas relacionadas con blockchain a través del lenguaje natural.

Conexión usando Claude CLI

Si está usando Claude CLI, puede conectarse al servidor MCP con solo dos comandos:

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

# Start Claude with the MCP server enabled
claude

Ejemplo: obtención de un saldo de token con 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
// }

Ejemplo: resolución de un nombre 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"
// }

Ejemplo: ejecución de múltiples llamadas por lotes con 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" }
//   ]
// }

📚 Referencia de la API

Herramientas

El servidor proporciona 25 herramientas MCP enfocadas para agentes. Todas las herramientas que aceptan parámetros de dirección admiten tanto direcciones de Ethereum como nombres ENS.

Información de la billetera

Nombre de la Herramienta	Descripción	Parámetros Clave
`get_wallet_address`	Obtener la dirección de la billetera configurada (de EVM_PRIVATE_KEY)	ninguno

Información de Red

Nombre de la Herramienta	Descripción	Parámetros Clave
`get_chain_info`	Obtener información de la red	`network`
`get_supported_networks`	Listar todas las redes EVM compatibles	ninguno
`get_gas_price`	Obtener los precios actuales de gas en una red	`network`

Servicios ENS

Nombre de la Herramienta	Descripción	Parámetros Clave
`resolve_ens_name`	Resolver nombre ENS a dirección	`ensName`, `network`
`lookup_ens_address`	Búsqueda inversa de dirección a nombre ENS	`address`, `network`

Información de Bloques y Transacciones

Nombre de la Herramienta	Descripción	Parámetros Clave
`get_block`	Obtener datos de bloque	`blockNumber` o `blockHash`, `network`
`get_latest_block`	Obtener datos del último bloque	`network`
`get_transaction`	Obtener detalles de transacción	`txHash`, `network`
`get_transaction_receipt`	Obtener recibo de transacción con registros	`txHash`, `network`
`wait_for_transaction`	Esperar confirmación de transacción	`txHash`, `confirmations`, `network`

Información de Saldos y Tokens

Nombre de la Herramienta	Descripción	Parámetros Clave
`get_balance`	Obtener saldo de token nativo	`address` (dirección/ENS), `network`
`get_token_balance`	Verificar saldo de token ERC20	`tokenAddress` (dirección/ENS), `ownerAddress` (dirección/ENS), `network`
`get_allowance`	Verificar asignación de gasto de tokens	`tokenAddress` (dirección/ENS), `ownerAddress` (dirección/ENS), `spenderAddress` (dirección/ENS), `network`

Interacciones con Contratos Inteligentes

Nombre de la Herramienta	Descripción	Parámetros Clave
`get_contract_abi`	Obtener ABI de contrato desde el explorador de bloques (más de 60 redes)	`contractAddress` (dirección/ENS), `network`
`read_contract`	Leer estado de contrato inteligente (obtiene ABI automáticamente si es necesario)	`contractAddress`, `functionName`, `args[]`, `abiJson` (opcional), `network`
`write_contract`	Ejecutar funciones que cambian estado (obtiene ABI automáticamente si es necesario)	`contractAddress`, `functionName`, `args[]`, `value` (opcional), `abiJson` (opcional), `network`
`multicall`	Ejecutar múltiples llamadas de lectura en una sola solicitud RPC (usa Multicall3)	`calls[]` (arreglo de llamadas a contratos), `allowFailure` (opcional), `network`

Transferencias de Tokens

Nombre de la Herramienta	Descripción	Parámetros Clave
`transfer_native`	Enviar tokens nativos (ETH, etc.)	`to` (dirección/ENS), `amount`, `network`
`transfer_erc20`	Transferir tokens ERC20	`tokenAddress` (dirección/ENS), `to` (dirección/ENS), `amount`, `network`
`approve_token_spending`	Aprobar asignaciones de tokens	`tokenAddress` (dirección/ENS), `spenderAddress` (dirección/ENS), `amount`, `network`

Servicios NFT

Nombre de la Herramienta	Descripción	Parámetros Clave
`get_nft_info`	Obtener metadatos de NFT (ERC721)	`tokenAddress` (dirección/ENS), `tokenId`, `network`
`get_erc1155_balance`	Verificar saldo ERC1155	`tokenAddress` (dirección/ENS), `tokenId`, `ownerAddress` (dirección/ENS), `network`

Firma de Mensajes

Nombre de la Herramienta	Descripción	Parámetros Clave
`sign_message`	Firmar mensajes arbitrarios para autenticación y verificación (SIWE, firmas fuera de cadena)	`message`
`sign_typed_data`	Firmar datos estructurados EIP-712 para transacciones sin gas, permisos y meta-transacciones	`domainJson`, `typesJson`, `primaryType`, `messageJson`

Recursos

El servidor expone datos de blockchain a través de los siguientes URI de recursos MCP. Todos los URI de recursos que aceptan direcciones también admiten nombres ENS, que se resuelven automáticamente a direcciones.

Recursos de Blockchain

Patrón de URI de Recurso	Descripción
`evm://{network}/chain`	Información de cadena para una red específica
`evm://chain`	Información de cadena de la red principal de Ethereum
`evm://{network}/block/{blockNumber}`	Datos de bloque por número
`evm://{network}/block/latest`	Datos del último bloque
`evm://{network}/address/{address}/balance`	Saldo de token nativo
`evm://{network}/tx/{txHash}`	Detalles de transacción
`evm://{network}/tx/{txHash}/receipt`	Recibo de transacción con registros

Recursos de Tokens

Patrón de URI de Recurso	Descripción
`evm://{network}/token/{tokenAddress}`	Información de token ERC20
`evm://{network}/token/{tokenAddress}/balanceOf/{address}`	Saldo de token ERC20
`evm://{network}/nft/{tokenAddress}/{tokenId}`	Información de token NFT (ERC721)
`evm://{network}/nft/{tokenAddress}/{tokenId}/isOwnedBy/{address}`	Verificación de propiedad de NFT
`evm://{network}/erc1155/{tokenAddress}/{tokenId}/uri`	URI de token ERC1155
`evm://{network}/erc1155/{tokenAddress}/{tokenId}/balanceOf/{address}`	Saldo de token ERC1155

🔒 Consideraciones de Seguridad

Las claves privadas se utilizan solo para firmar transacciones y nunca son almacenadas por el servidor
Considere implementar mecanismos de autenticación adicionales para uso en producción
Use HTTPS para el servidor HTTP en entornos de producción
Implemente limitación de velocidad para prevenir abusos
Para servicios de alto valor, considere agregar pasos de confirmación

📁 Estructura del Proyecto

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

🛠️ Desarrollo

Para modificar o extender el servidor:

Agregue nuevos servicios en el archivo apropiado bajo src/core/services/
Registre nuevas herramientas en src/core/tools.ts
Registre nuevos recursos en src/core/resources.ts
Agregue soporte para nuevas redes en src/core/chains.ts
Para cambiar la configuración del servidor, edite los valores codificados en src/server/http-server.ts

📄 Licencia

Este proyecto está licenciado bajo los términos de la Licencia MIT.