🌐 PortalMCP

通用以太坊 AI 网关

一个服务器。连接所有 AI。掌控整个链。

将任何模型上下文协议 (MCP) 客户端（Claude、ChatGPT、Gemini、Cursor、Windsurf、Cline、自定义代理等）通过自然语言接入以太坊。检查余额、兑换代币、铸造 NFT、生成并部署智能合约。

👁 MCP SDK
👁 Ethers
👁 TypeScript
👁 License
👁 Release

快速开始 · 设置 · 工具 · 路线图 · 更新日志

✨ 为什么选择 PortalMCP

大多数 AI 区块链集成将你锁定在单一 LLM 或单一客户端中。PortalMCP 是一个符合规范的 MCP 服务器 —— 同一个服务器，无论是在本地运行还是在 VPS 上运行，都能为所有支持 MCP 的客户端提供支持。

🔐 非托管 —— 私钥永远不会离开你的机器 🛰️ 实时链上上下文 —— 资源将 ETH 余额、交易回执和代币元数据直接流式传输到你的对话中 🛡️ 安全第一 —— 每个工具都声明了读取/破坏性/幂等性提示，以便客户端在广播前进行确认 🧩 通用 —— 支持 stdio 和 HTTP，可与现有的所有 MCP 客户端配合使用

Related MCP server: MCP Crypto Wallet EVM

🧭 兼容客户端

🎯 功能概览

⚡ 常规

📜 智能合约

🪙 ERC-20 代币

🖼️ ERC-721 NFT

🏦 DeFi

• /swap_tokens — 引导式代币兑换流程

• /deploy_erc20 — 生成 → 编译 → 部署端到端流程

🚀 快速开始

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

🔌 客户端设置

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

重启 Claude Desktop。17 个工具、eth:// 资源和两个斜杠命令将自动出现。

1. 使用公共 HTTPS URL（Caddy / Cloudflare Tunnel / Nginx）托管 HTTP 服务器。

2. 设置 MCP_HTTP_TOKEN=<long-random-string> 以确保只有你能调用它。

3. 在 Claude.ai → 设置 → 连接器 → 添加自定义连接器：

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

   • Auth: Authorization: Bearer <MCP_HTTP_TOKEN>

4. 同时适用于网页版和移动端 App。

所有这些工具都原生支持 MCP。在它们的 MCP 配置中添加一个指向以下内容的条目：

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

（与 Claude Desktop 的 stdio 命令相同。）

首选 — MCP 连接器 (ChatGPT Team/Enterprise, Gemini/Vertex Agents)： 指向 https://your-host/mcp，可选择添加 Bearer token。

传统 REST (ChatGPT 自定义 GPT 操作或任何 HTTP 代理)：

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

💬 对话示例

从零部署代币

“部署一个名为 PortalToken (PRTL) 的 ERC-20 代币，初始供应量为 1,000,000。”

→ eth_generate_contract → 显示代码 → eth_compile_contract → eth_deploy_contract_with_signer → 返回合约地址 + Etherscan 链接。

通用兑换

“将 0.01 ETH 兑换为 USDC。”

→ eth_swap_tokens { tokenIn:"ETH", tokenOut:"USDC", amount:"0.01" } — 批准（如果需要）并通过 Uniswap V3 执行。

实时链上上下文

“vitalik.eth 的余额是多少？”

→ 客户端将 eth://balance/0xd8dA… 资源直接附加到对话中。

⚙️ 配置

全部通过环境变量（.env 文件或主机环境变量）进行配置。完整列表请见 .env.example。

💡 占位符检测 — 任何以 your_, changeme, xxx, placeholder, <…> 开头的环境变量值都将被视为未设置。这能有效防止静默配置错误。

🌍 支持的网络

🛡️ 安全性

• 🚫 切勿提交 .env — 已包含在 .gitignore 中。

• 🔑 DEPLOYER_PRIVATE_KEY 是危险品。 请使用仅包含可承受损失资金的专用代理钱包。

• 🛰️ 在本地主机之外暴露 HTTP 时，务必设置 MCP_HTTP_TOKEN，并在前面加上 TLS (Caddy/Cloudflare)。

• 🧪 优先使用测试网 — 开发时使用 sepolia，仅在验证流程后才使用主网。

• 🏷️ 工具注释允许客户端在执行破坏性交易前进行提示 — 请勿自动批准它们。

• 👀 审查生成的 Solidity — eth_generate_contract 只是一个起点，而非审计结果。

🧑💻 开发

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

仓库布局

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

🏗️ 架构

 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.md。

🤝 贡献

欢迎提交 PR！优先领域：更多的 outputSchema 覆盖、额外工具、Docker 打包、Python 客户端、测试覆盖率。对于非琐碎的更改，请先开启一个 issue。

⭐ 给此仓库加星 · 🐛 报告问题 · 📜 MIT 许可证

由 Portal Foundation 倾心打造 💜

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers