🌐 PortalMCP

Universal AI gateway to Ethereum

One server. Every AI. The whole chain.

Plug any Model-Context-Protocol client — Claude, ChatGPT, Gemini, Cursor, Windsurf, Cline, custom agents — into Ethereum with natural language. Check balances, swap tokens, mint NFTs, generate and deploy smart contracts.

Quick start · Setup · Tools · Roadmap · Changelog

✨ Why PortalMCP

Most AI-blockchain integrations lock you to one LLM or one client. PortalMCP is a spec-compliant MCP server — the same server, running locally or on your VPS, powers every MCP-capable client.

🔐 Non-custodial — private keys never leave your machine 🛰️ Live chain context — resources stream ETH balances, tx receipts and token metadata straight into your chat 🛡️ Safety-first — every tool declares read/destructive/idempotent hints so clients can confirm before broadcasting 🧩 Universal — works over both stdio and HTTP, plays with every MCP client out there

🧭 Compatible clients

🎯 What it can do

⚡ General

📜 Smart contracts

🪙 ERC-20 tokens

🖼️ ERC-721 NFTs

🏦 DeFi

• /swap_tokens — guided token-swap flow

• /deploy_erc20 — generate → compile → deploy end-to-end

🚀 Quick start

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

🔌 Client setup

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %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-..."
      }
    }
  }
}

Restart Claude Desktop. 17 tools, eth:// resources, and two slash commands appear automatically.

1. Host the HTTP server with a public HTTPS URL (Caddy / Cloudflare Tunnel / Nginx).

2. Set MCP_HTTP_TOKEN=<long-random-string> so only you can call it.

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

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

   • Auth: Authorization: Bearer <MCP_HTTP_TOKEN>

4. Works on both web and the mobile app.

All speak MCP natively. Add an entry to their MCP config pointing at:

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

(Same stdio command as Claude Desktop.)

Preferred — MCP connector (ChatGPT Team/Enterprise, Gemini/Vertex Agents): Point at https://your-host/mcp, optionally with a Bearer token.

Legacy REST (ChatGPT Custom GPT Actions or any HTTP agent):

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

💬 Example conversations

Deploy a token from scratch

"Deploy an ERC-20 called PortalToken (PRTL) with initial supply 1,000,000."

→ eth_generate_contract → shows code → eth_compile_contract → eth_deploy_contract_with_signer → returns the contract address + Etherscan link.

Universal swap

"Swap 0.01 ETH for USDC."

→ eth_swap_tokens { tokenIn:"ETH", tokenOut:"USDC", amount:"0.01" } — approves (if needed) and executes via Uniswap V3.

Live on-chain context

"What's the balance of vitalik.eth?"

→ client attaches the eth://balance/0xd8dA… resource straight into the conversation.

⚙️ Configuration

All via env vars (.env file or host env). Full list in .env.example.

💡 Placeholder detection — any env value starting with your_, changeme, xxx, placeholder, <…> is treated as unset. Stops silent misconfigurations dead.

🌍 Networks supported

🛡️ Security

• 🚫 Never commit .env — already in .gitignore.

• 🔑 DEPLOYER_PRIVATE_KEY is a loaded gun. Use a dedicated agent wallet with only funds you can lose.

• 🛰️ Always set MCP_HTTP_TOKEN when exposing HTTP beyond localhost, and put TLS (Caddy/Cloudflare) in front.

• 🧪 Testnet first — use sepolia for development, mainnet only after you've verified the flow.

• 🏷️ Tool annotations let clients prompt before destructive txs — don't auto-approve them.

• 👀 Review generated Solidity — eth_generate_contract is a starting point, not an audit.

🧑‍💻 Development

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

Repo layout

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

🏗️ Architecture

          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)

🗺️ Roadmap highlights

Full plan in ROADMAP.md.

🤝 Contributing

PRs welcome! Priority areas: more outputSchema coverage, additional tools, Docker packaging, Python client, test coverage. Open an issue first for non-trivial changes.

⭐ Star this repo · 🐛 Report an issue · 📜 MIT License

Built with 💜 by the Portal Foundation