使用说明

🌐 PortalMCP

通往以太坊的通用人工智能网关

一台服务器。每一个AI，整个链条。

使用自然语言将任何模型上下文协议客户端（Claude、ChatGPT、Gemini、Cursor、Windsurf、Cline、自定义代理）插入以太坊。检查余额、交换代币、创建NFT、生成和部署智能合约。

快速启动 · 设置 · 工具 · 路线图 · 更新日志

✨ 为什么选择PortalMCP

大多数AI区块链集成将您锁定到一个LLM或一个客户端。PortalMCP符合规范 MCP服务器 --同一台服务器，在本地或您的VPS上运行，为每个支持MCP的客户端供电。

🔐 无监护权的 --私钥永远不会离开你的机器 🛰️ 直播链上下文 --资源将ETH余额、tx收据和令牌元数据直接传输到您的聊天中 🛡️ 安全第一 --每个工具都声明读取/破坏/幂等提示，以便客户端在广播之前进行确认 🧩 通用 --通过stdio和HTTP工作，与所有MCP客户端一起运行

🧭 兼容客户端

客户	运输	注意事项
🟣 克劳德桌面版（macOS/Windows）	stdio	插入下面的配置
🌐 Claude.ai网络+移动	HTTP	添加为自定义连接器（专业/团队/企业）
💻 克劳德代码/CLI	要么
🧠 光标·风帆·Cline·继续·Zed AI	stdio	本地MCP
💬 ChatGPT （团队/企业）	HTTP	MCP连接器
🛠️ ChatGPT自定义GPT	REST	使用捆绑 `openapi.json`
✴️ 谷歌Gemini/Vertex代理	HTTP	MCP连接器
🐍 LangChain·LlamaIndex·OpenAI代理SDK	通过他们的MCP适配器
🤖 任何HTTP代理	HTTP	纯JSON-RPC+SSE打开 `/mcp`

🎯 它能做什么

17 tools — click to expand

⚡ 通用

工具	动作
`eth_get_balance`	任何地址或默认钱包的ETH余额
`eth_call_contract`	针对任何合约的只读调用+ABI
`eth_send_transaction`	准备一个通用的未签名交易

📜 智能合约

工具	动作
`eth_generate_contract`	克劳德从自然语言中创作了《Solidity》
`eth_compile_contract`	solc编译→ 字节码+ABI
`eth_deploy_contract`	为外部钱包签名准备部署tx
`eth_deploy_contract_with_signer`	使用直接部署 `DEPLOYER_PRIVATE_KEY`

🪙 ERC-20代币

工具	动作
`eth_create_token`	生成ERC-20实体
`eth_get_token_balance`	任何持有人的ERC-20余额
`eth_transfer_token`	已签名的转账或未签名的交易准备

🖼️ ERC-721 NFT

工具	动作
`eth_create_nft_collection`	生成ERC-721实体
`eth_mint_nft`	准备 `mint` / `safeMint` / `mintWithURI`
`eth_get_nft_owner`	`ownerOf()` 查找

🏦 德菲

工具	动作
`eth_create_staking_contract`	生成立桩坚固性
`eth_stake_tokens`	准备批准+股份交易
`eth_swap_tokens`	通用Uniswap V3交换（任何ERC-20对）
`eth_swap_eth_to_usdt`	上述便利别名

4 resources (live chain data as context)

URI	返回
`eth://wallet`	已配置签名者地址、网络、ETH余额
`eth://balance/{address}`	任何地址的实时ETH余额
`eth://tx/{hash}`	交易+收据（状态、气体、区块、日志、浏览器URL）
`eth://token/{address}`	ERC-20元数据（名称、符号、小数、总供应量）

2 prompts (slash commands)

/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

🔌 客户端设置

🟣 Claude Desktop (stdio)

编辑 ~/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-..."
      }
    }
  }
}

重新启动克劳德桌面。17个工具， eth:// 资源，两个斜线命令会自动出现。

🌐 Claude.ai web / mobile (Streamable HTTP)

使用公共HTTPS URL（Caddy/CCloudflare Tunnel/Nginx）托管HTTP服务器。
集 MCP_HTTP_TOKEN=<long-random-string> 所以只有你才能称之为。
在Claude.ai中→ 设置→ 连接器→ 添加自定义连接器:
- 网址： https://your-host.example.com/mcp
- 认证： Authorization: Bearer <MCP_HTTP_TOKEN>
适用于网络和移动应用程序。

🧠 Cursor / Windsurf / Cline / Continue

所有人都母语为MCP。在他们的MCP配置中添加一个条目，指向：

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

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

💬 ChatGPT, Gemini, custom agents

首选-MCP连接器 （ChatGPT团队/企业，Gemini/Vertex代理）：指向 https://your-host/mcp，可选地使用Bearer令牌。

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

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

💬 示例对话

从头开始部署令牌

“部署一个名为PortalToken（PRTL）的ERC-20，初始供应量为1000000。”

→ 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 文件或主机环境变量）。完整列表在 .env.example.

变量	必需	目的
`ETHEREUM_NETWORK`	–	`mainnet`, `sepolia`, `arbitrum`, `optimism`, `base`, `polygon`，…（默认值 `mainnet`)
`ETHEREUM_RPC_URL`	⭐	完整的JSON-RPC URL--覆盖Infura/Alchemy密钥设置
`ALCHEMY_API_KEY`	alt	Key only——PortalMCP打造现代 `g.alchemy.com` URL
`INFURA_API_KEY`	alt	Infura项目ID
`DEPLOYER_PRIVATE_KEY`	写	`0x`-前缀十六进制--启用签名者支持的工具
`ANTHROPIC_API_KEY`	生成	For `eth_generate_contract`
`ANTHROPIC_MODEL`	–	覆盖默认值 `claude-sonnet-4-5-20250929`
`MCP_HTTP_PORT`	–	默认值 `3333`
`MCP_HTTP_HOST`	–	默认值 `0.0.0.0`
`MCP_HTTP_TOKEN`	🛡️	HTTP传输的承载令牌
`MCP_HTTP_CORS_ORIGIN`	–	默认值 `*`

💡 占位符检测 --任何以以下开头的env值 your_, changeme, xxx, placeholder, <…> 被视为未凝固。停止无声的错误配置。

🌍 支持的网络

L1	Ethereum mainnet · Sepolia · Goerli · Holesky
L2	Arbitrum · Optimism · Base · Polygon (+ every testnet)
Custom	Any EVM chain — BSC, Avalanche, Linea, zkSync, … — via `ETHEREUM_RPC_URL`

🛡️ 安全

🚫 永不承诺 .env --已经在 .gitignore.
🔑 DEPLOYER_PRIVATE_KEY 是一把上膛的枪。 使用专用的代理钱包，只保留您可能会损失的资金。
🛰️ 始终设置 MCP_HTTP_TOKEN 在本地主机之外公开HTTP时，将TLS（Caddy/CCloudflare）放在前面。
🧪 先测试网 --使用 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

脚本	目的
`npm start`	stdio MCP服务器（prod）
`npm run start:http`	流式HTTP MCP服务器（prod）
`npm run start:api`	ChatGPT操作/HTTP客户端的传统REST
`npm run smoke`	注册烟雾测试——非常适合CI

回购布局

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)

🗺️ 路线图亮点

Shipped ✅

MCP SDK 1.29 — stdio + HTTP
17 tools · 1 resource · 3 templates · 2 prompts
Tool annotations + outputSchema
Universal Uniswap V3 swap
L1 + L2 + testnets
Anthropic SDK 0.90 · Claude Sonnet 4.5
Smoke test for CI

Next 🔭

Elicitation (confirm destructive txs)
ENS / gas helpers
Tx simulation with revert decoding
Multi-DEX aggregation (1inch, 0x)
Aave / Compound read positions
Ledger hardware signer
Gnosis Safe + ERC-4337
Docker + Python SDK

完整计划 ROADMAP.md.

🤝 贡献

PR欢迎！优先领域：更多 outputSchema 覆盖率、附加工具、Docker打包、Python客户端、测试覆盖率。首先打开一个问题，进行非琐碎的更改。

⭐ 标记此回购 · 🐛 报告问题 · 📜 MIT许可证

内置于💜 由 门户基础