🌐 PortalMCP

이더리움을 위한 범용 AI 게이트웨이

하나의 서버. 모든 AI. 전체 체인.

Claude, ChatGPT, Gemini, Cursor, Windsurf, Cline, 커스텀 에이전트 등 모든 Model-Context-Protocol 클라이언트를 자연어로 이더리움에 연결하세요. 잔액 확인, 토큰 스왑, NFT 민팅, 스마트 컨트랙트 생성 및 배포가 가능합니다.

👁 MCP SDK
👁 Ethers
👁 TypeScript
👁 License
👁 Release

빠른 시작 · 설정 · 도구 · 로드맵 · 변경 로그

✨ PortalMCP를 선택해야 하는 이유

대부분의 AI-블록체인 통합은 특정 LLM이나 클라이언트에 종속됩니다. PortalMCP는 사양을 준수하는 MCP 서버로, 로컬이나 VPS에서 실행되는 동일한 서버가 모든 MCP 호환 클라이언트를 지원합니다.

🔐 비수탁형(Non-custodial) — 개인 키는 절대 기기를 떠나지 않습니다. 🛰️ 실시간 체인 컨텍스트 — 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=<긴-랜덤-문자열>을 설정하여 본인만 호출할 수 있도록 합니다.

3. Claude.ai → 설정 → 커넥터 → 커스텀 커넥터 추가:

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

   • 인증: Authorization: Bearer <MCP_HTTP_TOKEN>

4. 웹과 모바일 앱 모두에서 작동합니다.

모두 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 토큰을 사용하세요.

레거시 REST (ChatGPT Custom GPT Actions 또는 모든 HTTP 에이전트):

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

💬 대화 예시

처음부터 토큰 배포하기

*"초기 공급량 1,000,000개인 PortalToken(PRTL)이라는 ERC-20 토큰을 배포해줘."

→ 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 클라이언트, 테스트 커버리지. 사소하지 않은 변경 사항은 먼저 이슈를 열어주세요.

⭐ 저장소 별표하기 · 🐛 이슈 보고하기 · 📜 MIT 라이선스

Portal Foundation이 💜를 담아 제작함

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers