telegraph

@telegraph/mcp-server

将 Telegraph Protocol AI 推理 API 作为工具提供的 MCP 服务，并支持自动 x402 微支付。

它可将任何兼容 MCP 的 Agent（Claude Desktop、Cursor、ElizaOS、LangChain、OpenClaw、Goose 等）连接到 Telegraph 的 AI 矿工网络，提供天气预报、深度伪造检测、大模型推理、AI 文本检测、信号监控等能力，Agent 无需编写任何加密货币代码。MCP 服务会在内部处理私钥托管、支付签名和交易结算。

矿工可以是 Bittensor 子网、托管模型，或通过 YAML 集成的任何私有 API。出于历史原因，部分工具和字段名称仍使用 subnet，请将其理解为“矿工”。

文档

文档	描述
架构	MCP 协议、工具类别、x402 自动支付、客户端集成
故障排除	常见问题和解决方案

快速开始

选项 A — npx（无需克隆，建议在发布后使用）

TELEGRAPH_NODE_URL=http://13.237.89.59:7044 \
TELEGRAPH_ENGINE_URL=http://13.237.89.59:8080 \
TELEGRAPH_DAEMON_URL=http://13.237.89.59:8081 \
TELEGRAPH_EVM_PRIVATE_KEY=0xyour_key_here \
npx -y telegraph-protocol-mcp

选项 B — 从源码开始

# 1. Clone and enter
git clone https://github.com/telegraphprotocol/telegraph-mcp
cd telegraph-mcp

# 2. Copy and edit .env
cp .env.example .env
# Edit: set TELEGRAPH_EVM_PRIVATE_KEY=0xyour_key_here

# 3. Install and build
npm install && npm run build

# 4. Run
npm start

已以 telegraph-protocol-mcp 发布到 npm，并以 io.github.telegraphprotocol/telegraph 列入 MCP Registry。维护者请参阅 PUBLISHING.md。

架构

Agent (Claude / Cursor / Eliza / etc.)
       │
       │ MCP protocol (JSON-RPC over stdio)
       │
┌──────▼─────────────────────────────────────────┐
│  Telegraph MCP Server (runs locally)            │
│                                                 │
│  ┌─────────┐  ┌──────────┐  ┌───────────────┐  │
│  │ Node    │  │ Engine   │  │ Daemon        │  │
│  │ :7044   │  │ :8080    │  │ :8081         │  │
│  ├─────────┤  ├──────────┤  ├───────────────┤  │
│  │ Status  │  │ Subnets  │  │ Health        │  │
│  │ Health  │  │ Ask      │  │ Categories    │  │
│  │ Subnets │  │ Direct   │  │ Questions     │  │
│  │ Dynamic │  │          │  │               │  │
│  └─────────┘  └──────────┘  └───────────────┘  │
│                                                 │
│  X402 payment handled transparently:            │
│    request → 402 → sign EIP-3009 → retry        │
└─────────────────────────────────────────────────┘

配置

所有配置均通过环境变量设置（.env 文件或内联设置）：

变量	必需	默认值	描述
TELEGRAPH_NODE_URL	是	http://localhost:7044	Telegraph 节点 URL
TELEGRAPH_ENGINE_URL	是	http://localhost:8080	引擎服务 URL
TELEGRAPH_DAEMON_URL	是	http://localhost:8081	守护进程 API URL
TELEGRAPH_EVM_PRIVATE_KEY	是*	—	EVM 私钥（以 0x 开头的十六进制字符串）
TELEGRAPH_SOLANA_PRIVATE_KEY	否*	—	Solana 私钥（base58）
EVM_NETWORK	否	eip155:*	EVM CAIP-2 网络
SVM_NETWORK	否	solana:*	Solana CAIP-2 网络
REFRESH_INTERVAL_MS	否	300000	矿工工具刷新间隔（毫秒）。设为 0 可禁用。

*至少需要一个私钥。

可用工具

节点工具（无需支付）

工具	描述
tg_node_status	节点状态、公钥、链信息
tg_node_subnets_health	矿工集成健康检查
tg_node_list_subnets	包含元数据、架构和端点的完整矿工目录

引擎工具

工具	支付	描述
tg_engine_list_subnets	免费	列出引擎可路由到的矿工
tg_engine_ask	x402	自动路由推理（大模型会为查询选择最佳矿工）
tg_engine_ask_subnet	x402	通过 ID 指定的矿工直接进行推理

守护进程工具（无需支付）

工具	描述
tg_daemon_health	守护进程健康检查
tg_daemon_categories	信号类别（POLITICS、ECONOMICS、TECHNOLOGY、CLIMATE、HEALTH、CRYPTO、SPORTS、…）
tg_daemon_questions	使用筛选条件（类别、来源、时间、兴趣）查询收集到的信号

动态矿工工具（自动发现，x402 付款）

每个矿工端点的工具均根据 Telegraph 节点的实时集成注册表自动生成。实时工具集会随链上状态变化，因此请将其视为快照，而非事实来源（调用 tg_node_list_subnets 获取当前目录）：

矿工	工具
Zeus (18) — 天气	tg_zeus_predict
ItsAI (32) — AI 文本检测	tg_itsai_text_detector_detect
Sapling (33) — AI 内容检测	tg_sapling_ai_detector_detect
BitMind (34) — Deepfake	tg_bitmind_detect_image、tg_bitmind_detect_video、tg_bitmind_preprocess_video、tg_bitmind_get_video_upload_url
OpenAI (102) — 大模型 / 图像	tg_openai_chat、tg_openai_responses、tg_openai_embed、tg_openai_images_generate、tg_openai_moderate

这些工具会自动更新。 链上注册的新矿工会在 5 分钟内显示。已注销的矿工会被清理。Agent 始终只能看到当前有效的工具。

出于历史原因，部分工具和字段名称中包含 subnet——Telegraph 最初通过集成 Bittensor 子网开展业务。如今，任何通过 YAML 集成的提供方都是矿工，无论是否使用子网。

x402 付款的工作原理

当 Agent 调用付费工具（例如 tg_engine_ask）时：

1. MCP 服务向 Telegraph 发送请求
2. Telegraph 返回 HTTP 402，并在响应标头中提供付款要求
3. @x402/fetch 拦截 402，使用你的私钥签署 EIP-3009 TransferWithAuthorization，将签名附加为 PAYMENT 标头，然后重试
4. Telegraph 通过 PayAI facilitator 在链上验证付款，并返回结果

Agent 和大模型都不会看到付款流程、私钥或区块链交易。 整个过程完全透明——Agent 只会看到一个返回结果的工具。

集成指南

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）。

使用 npx（最简单——无需克隆或构建）：

{
  "mcpServers": {
    "telegraph": {
      "command": "npx",
      "args": ["-y", "telegraph-protocol-mcp"],
      "env": {
        "TELEGRAPH_NODE_URL": "http://13.237.89.59:7044",
        "TELEGRAPH_ENGINE_URL": "http://13.237.89.59:8080",
        "TELEGRAPH_DAEMON_URL": "http://13.237.89.59:8081",
        "TELEGRAPH_EVM_PRIVATE_KEY": "0xyour_key_here"
      }
    }
  }
}

或指向本地构建：

{
  "mcpServers": {
    "telegraph": {
      "command": "node",
      "args": ["/path/to/telegraph-mcp/dist/index.js"],
      "env": {
        "TELEGRAPH_NODE_URL": "http://13.237.89.59:7044",
        "TELEGRAPH_ENGINE_URL": "http://13.237.89.59:8080",
        "TELEGRAPH_DAEMON_URL": "http://13.237.89.59:8081",
        "TELEGRAPH_EVM_PRIVATE_KEY": "0xyour_key_here"
      }
    }
  }
}

重启 Claude Desktop。Telegraph 工具将显示在工具列表中。试着询问 “拉合尔的天气怎么样？” 或 “使用 Telegraph 引擎解释一下 Bitcoin 是什么。”

Cursor

前往 Cursor Settings → MCP → Add new MCP server 并添加：

{
  "mcpServers": {
    "telegraph": {
      "command": "node",
      "args": ["/path/to/telegraph-mcp/dist/index.js"],
      "env": {
        "TELEGRAPH_NODE_URL": "http://13.237.89.59:7044",
        "TELEGRAPH_ENGINE_URL": "http://13.237.89.59:8080",
        "TELEGRAPH_DAEMON_URL": "http://13.237.89.59:8081",
        "TELEGRAPH_EVM_PRIVATE_KEY": "0xyour_key_here"
      }
    }
  }
}

ElizaOS

在 Eliza 角色文件或 MCP 插件配置中：

{
  "mcp": {
    "telegraph": {
      "command": "node",
      "args": ["/path/to/telegraph-mcp/dist/index.js"],
      "env": {
        "TELEGRAPH_NODE_URL": "http://13.237.89.59:7044",
        "TELEGRAPH_ENGINE_URL": "http://13.237.89.59:8080",
        "TELEGRAPH_DAEMON_URL": "http://13.237.89.59:8081",
        "TELEGRAPH_EVM_PRIVATE_KEY": "0xyour_key_here"
      }
    }
  }
}

ElizaOS v0.25+ 通过 @elizaos/plugin-mcp 包支持 MCP。在角色的插件列表中启用它：

{
  "plugins": ["@elizaos/plugin-mcp"]
}

LangChain / LangGraph

LangChain 通过 langchain-mcp-adapters 支持 MCP：

pip install langchain-mcp-adapters

from langchain_mcp_adapters.client import MultiServerMCPClient

client = MultiServerMCPClient({
    "telegraph": {
        "command": "node",
        "args": ["/path/to/telegraph-mcp/dist/index.js"],
        "env": {
            "TELEGRAPH_NODE_URL": "http://13.237.89.59:7044",
            "TELEGRAPH_ENGINE_URL": "http://13.237.89.59:8080",
            "TELEGRAPH_DAEMON_URL": "http://13.237.89.59:8081",
            "TELEGRAPH_EVM_PRIVATE_KEY": "0xyour_key_here",
        },
        "transport": "stdio",
    }
})

tools = client.get_tools()
# Use tools with your LangChain agent

TypeScript/Node.js：

npm install @langchain/mcp-adapters

import { MultiServerMCPClient } from "@langchain/mcp-adapters";

const client = new MultiServerMCPClient({
  telegraph: {
    command: "node",
    args: ["/path/to/telegraph-mcp/dist/index.js"],
    env: {
      TELEGRAPH_NODE_URL: "http://13.237.89.59:7044",
      TELEGRAPH_ENGINE_URL: "http://13.237.89.59:8080",
      TELEGRAPH_DAEMON_URL: "http://13.237.89.59:8081",
      TELEGRAPH_EVM_PRIVATE_KEY: "0xyour_key_here",
    },
    transport: "stdio",
  },
});

const tools = await client.getTools();

OpenClaw

OpenClaw 通过配置原生支持 MCP。在 openclaw.config.json 中添加：

{
  "mcpServers": {
    "telegraph": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/telegraph-mcp/dist/index.js"],
      "env": {
        "TELEGRAPH_NODE_URL": "http://13.237.89.59:7044",
        "TELEGRAPH_ENGINE_URL": "http://13.237.89.59:8080",
        "TELEGRAPH_DAEMON_URL": "http://13.237.89.59:8081",
        "TELEGRAPH_EVM_PRIVATE_KEY": "0xyour_key_here"
      }
    }
  }
}

Goose

Goose 通过扩展系统支持 MCP 服务。在 ~/.config/goose/config.yaml 中配置：

extensions:
  telegraph:
    type: mcp
    command: node
    args:
      - /path/to/telegraph-mcp/dist/index.js
    env:
      TELEGRAPH_NODE_URL: http://13.237.89.59:7044
      TELEGRAPH_ENGINE_URL: http://13.237.89.59:8080
      TELEGRAPH_DAEMON_URL: http://13.237.89.59:8081
      TELEGRAPH_EVM_PRIVATE_KEY: 0xyour_key_here

VS Code / Continue

在 Continue 的 config.json 中：

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "node",
          "args": ["/path/to/telegraph-mcp/dist/index.js"],
          "env": {
            "TELEGRAPH_NODE_URL": "http://13.237.89.59:7044",
            "TELEGRAPH_ENGINE_URL": "http://13.237.89.59:8080",
            "TELEGRAPH_DAEMON_URL": "http://13.237.89.59:8081",
            "TELEGRAPH_EVM_PRIVATE_KEY": "0xyour_key_here"
          }
        }
      }
    ]
  }
}

通用 / 任意 MCP 客户端

该服务使用 MCP stdio 传输——这是本地 MCP 服务的标准传输方式。任何支持通过 stdio 使用 MCP 协议的客户端都可以使用它：

{
  "mcpServers": {
    "telegraph": {
      "command": "node",
      "args": ["/path/to/telegraph-mcp/dist/index.js"],
      "env": {
        "TELEGRAPH_NODE_URL": "http://13.237.89.59:7044",
        "TELEGRAPH_ENGINE_URL": "http://13.237.89.59:8080",
        "TELEGRAPH_DAEMON_URL": "http://13.237.89.59:8081",
        "TELEGRAPH_EVM_PRIVATE_KEY": "0xyour_key_here"
      }
    }
  }
}

动态工具发现

子网工具并非硬编码。服务启动时及此后每 5 分钟：

1. 从 Telegraph 节点的 GET /miner-dispatcher/integrations 获取实时集成
2. 与当前已注册的工具进行比对
3. 添加新子网 → 自动注册工具
4. 移除过期子网 → 删除工具
5. 向已连接的客户端发送 notifications/tools/list_changed

这意味着：

• 新子网会在链上注册后 5 分钟内自动显示——无需重启 MCP
• 已移除的子网会被清理——Agent 不会调用不存在的工具
• Agent 始终能准确了解网络上有哪些可用工具

安全

• 使用临时钱包。 切勿使用主钱包。仅存入推理所需的 USDC。
• 私钥保留在 MCP 进程中。 不会暴露给 Agent 或大模型。
• MCP 服务通过 stdio 在本地运行 — 不会暴露到网络。
• 按次付费：每次推理请求通常为 $0.01。

开发

npm install          # Install deps
npm run build        # Compile TypeScript
npm run dev          # Dev mode with tsx (hot reload)
npx @modelcontextprotocol/inspector dist/index.js  # Inspect tools