🌐 PortalMCP

Puerta de enlace de IA universal para Ethereum

Un servidor. Toda IA. Toda la cadena.

Conecta cualquier cliente del Protocolo de Contexto de Modelo (MCP) — Claude, ChatGPT, Gemini, Cursor, Windsurf, Cline, agentes personalizados — a Ethereum con lenguaje natural. Consulta saldos, intercambia tokens, acuña NFT, genera y despliega contratos inteligentes.

👁 MCP SDK
👁 Ethers
👁 TypeScript
👁 License
👁 Release

Inicio rápido · Configuración · Herramientas · Hoja de ruta · Registro de cambios

✨ Por qué PortalMCP

La mayoría de las integraciones de IA y blockchain te limitan a un LLM o un cliente. PortalMCP es un servidor MCP que cumple con las especificaciones: el mismo servidor, ejecutándose localmente o en tu VPS, potencia a cada cliente compatible con MCP.

🔐 Sin custodia — las claves privadas nunca abandonan tu máquina 🛰️ Contexto de cadena en vivo — los recursos transmiten saldos de ETH, recibos de transacciones y metadatos de tokens directamente a tu chat 🛡️ Seguridad primero — cada herramienta declara sugerencias de lectura/destructivas/idempotentes para que los clientes puedan confirmar antes de transmitir 🧩 Universal — funciona tanto sobre stdio como HTTP, interactúa con todos los clientes MCP existentes

Related MCP server: MCP Crypto Wallet EVM

🧭 Clientes compatibles

🎯 Qué puede hacer

⚡ General

📜 Contratos inteligentes

🪙 Tokens ERC-20

🖼️ NFT ERC-721

🏦 DeFi

• /swap_tokens — flujo guiado de intercambio de tokens

• /deploy_erc20 — generar → compilar → desplegar de extremo a extremo

🚀 Inicio rápido

git clone https://github.com/PortalFnd/PortalMCP.git
cd PortalMCP/portalmcp
npm install
cp .env.example .env
# fill in .env — ANTHROPIC_API_KEY, DEPLOYER_PRIVATE_KEY,
# and ETHEREUM_RPC_URL (or a real ALCHEMY_API_KEY)
npm run build
npm run smoke # ✓ 17 tools / 1 resource / 3 templates / 2 prompts
npm start # stdio (Claude Desktop, Cursor, …)
# or
npm run start:http # Streamable HTTP on http://0.0.0.0:3333/mcp

🔌 Configuración del cliente

Edita ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
 "mcpServers": {
 "portalmcp": {
 "command": "node",
 "args": ["/absolute/path/to/PortalMCP/portalmcp/dist/index.js"],
 "env": {
 "ETHEREUM_NETWORK": "mainnet",
 "ETHEREUM_RPC_URL": "https://eth-mainnet.g.alchemy.com/v2/YOUR_KEY",
 "DEPLOYER_PRIVATE_KEY": "0x...",
 "ANTHROPIC_API_KEY": "sk-ant-..."
 }
 }
 }
}

Reinicia Claude Desktop. 17 herramientas, recursos eth:// y dos comandos de barra aparecerán automáticamente.

1. Aloja el servidor HTTP con una URL HTTPS pública (Caddy / Cloudflare Tunnel / Nginx).

2. Configura MCP_HTTP_TOKEN=<cadena-larga-aleatoria> para que solo tú puedas llamarlo.

3. En Claude.ai → Settings → Connectors → Add Custom Connector:

   • URL: https://your-host.example.com/mcp

   • Auth: Authorization: Bearer <MCP_HTTP_TOKEN>

4. Funciona tanto en la web como en la aplicación móvil.

Todos hablan MCP de forma nativa. Añade una entrada a su configuración MCP apuntando a:

node /absolute/path/to/PortalMCP/portalmcp/dist/index.js

(El mismo comando stdio que Claude Desktop.)

Preferido — Conector MCP (ChatGPT Team/Enterprise, Gemini/Vertex Agents): Apunta a https://your-host/mcp, opcionalmente con un token Bearer.

REST heredado (Acciones de GPT personalizadas de ChatGPT o cualquier agente HTTP):

npm run start:api
# OpenAPI spec: http://localhost:3001/openapi.json

💬 Conversaciones de ejemplo

Desplegar un token desde cero

"Despliega un ERC-20 llamado PortalToken (PRTL) con un suministro inicial de 1,000,000."

→ eth_generate_contract → muestra código → eth_compile_contract → eth_deploy_contract_with_signer → devuelve la dirección del contrato + enlace a Etherscan.

Intercambio universal

"Intercambia 0.01 ETH por USDC."

→ eth_swap_tokens { tokenIn:"ETH", tokenOut:"USDC", amount:"0.01" } — aprueba (si es necesario) y ejecuta vía Uniswap V3.

Contexto en cadena en vivo

"¿Cuál es el saldo de vitalik.eth?"

→ el cliente adjunta el recurso eth://balance/0xd8dA… directamente a la conversación.

⚙️ Configuración

Todo mediante variables de entorno (archivo .env o entorno del host). Lista completa en .env.example.

💡 Detección de marcadores de posición — cualquier valor de entorno que comience con your_, changeme, xxx, placeholder, <…> se trata como no configurado. Detiene configuraciones erróneas silenciosas.

🌍 Redes compatibles

🛡️ Seguridad

• 🚫 Nunca subas .env — ya está en .gitignore.

• 🔑 DEPLOYER_PRIVATE_KEY es un arma cargada. Usa una billetera de agente dedicada solo con fondos que puedas permitirte perder.

• 🛰️ Configura siempre MCP_HTTP_TOKEN al exponer HTTP más allá de localhost, y coloca TLS (Caddy/Cloudflare) delante.

• 🧪 Primero testnet — usa sepolia para desarrollo, mainnet solo después de haber verificado el flujo.

• 🏷️ Las anotaciones de herramientas permiten a los clientes preguntar antes de txs destructivas — no las apruebes automáticamente.

• 👀 Revisa el Solidity generado — eth_generate_contract es un punto de partida, no una auditoría.

🧑💻 Desarrollo

npm install
npm run dev # stdio, ts-node hot-reload
npm run dev:http # HTTP, ts-node
npm run build # tsc → dist/
npm run smoke # assert MCP surface is registered
npm test # Jest

Diseño del repositorio

portalmcp/
├── src/
│ ├── index.ts # stdio entrypoint
│ ├── mcp-http.ts # Streamable HTTP entrypoint
│ ├── server-factory.ts # createPortalServer() — shared wiring
│ ├── smoke-test.ts # CI registration check
│ ├── tools/ # general · contracts · defi · tokens · nfts
│ ├── blockchain/ # EthereumService · CompilerService
│ ├── claude/ # ContractGenerator (Anthropic SDK)
│ ├── contracts/ # Solidity templates
│ └── adapters/ # Legacy REST / LangChain / OpenAI adapters
├── dist/ # tsc output
├── .env.example
└── package.json

🏗️ Arquitectura

 stdio Streamable HTTP (SSE)
┌─────────────────────┐ ┌─────────────────────────────┐
│ Claude Desktop │ │ Claude.ai web + mobile │
│ Cursor · Windsurf │ │ ChatGPT · Gemini │
│ Cline · Continue │ │ Custom agents │
└─────────┬───────────┘ └──────────────┬──────────────┘
 │ │
 │ ┌──────────────────────┐ │
 └───────▶│ PortalMCP server │◀────────────┘
 │ (server-factory.ts) │
 └──────────┬───────────┘
 │
 ┌──────────────────────┼──────────────────────┐
 ▼ ▼ ▼
 EthereumService Uniswap V3 Anthropic
 (ethers v6 + (eth_swap_tokens) (eth_generate_contract)
 Alchemy/Infura/
 custom RPC)

🗺️ Aspectos destacados de la hoja de ruta

Plan completo en ROADMAP.md.

🤝 Contribuyendo

¡Las PR son bienvenidas! Áreas prioritarias: más cobertura de outputSchema, herramientas adicionales, empaquetado Docker, cliente Python, cobertura de pruebas. Abre un issue primero para cambios no triviales.

⭐ Marca este repo con una estrella · 🐛 Informar de un problema · 📜 Licencia MIT

Construido con 💜 por la Portal Foundation

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers