X402 Claude MCP

x402克劳德MCP服务器

可重复使用 MCP（模型上下文协议）服务器 它使LLM代理能够使用CDP嵌入式钱包自主调用x402受保护的API。此服务器将配置的x402端点作为MCP工具公开，允许代理在不进行手动支付处理的情况下发现和使用付费API。

特性

• 自主支付：使用CDP嵌入式钱包自动处理x402支付
• 动态发现：代理通过MCP工具定义发现可用端点
• 灵活的配置：基于JSON的端点配置，支持环境变量
• 安全第一：信任模型确保只能调用已批准的端点
• 多网络支持：与Base、Base Sepolia、以太坊和Sepolia测试网合作
• 通用兼容性：与Claude Desktop、Claude Code、Codex、Gemini和其他MCP客户合作

先决条件

• Node.js>=18.0.0
• 带有USDC余额的CDP嵌入式钱包
• MCP兼容客户端（克劳德桌面、克劳德代码等）

快速入门（推荐）

最简单的入门方法是使用交互式设置向导：

npx x402-claude-mcp setup

运行安装程序的替代方法：

# If installed globally
npm install -g x402-claude-mcp
x402-claude-mcp setup

# Or with short flag
npx x402-claude-mcp --setup
npx x402-claude-mcp -s

# Or from local installation
npm run setup

安装向导的作用：

• ✅ 创建 ~/.x402-claude-mcp/ 目录
• ✅ 产生 endpoints.json 具有预配置的x402 API（二维码、元数据提取、GIF搜索等）
• ✅ 提示您输入CDP钱包私钥
• ✅ 更新 ~/Library/Application Support/Claude/claude_desktop_config.json 自动地
• ✅ 使用适当的环境变量配置MCP服务器

就是这样！ 重启Claude Desktop后，您将拥有一个钱包，可以开始使用x402受保护的API。

寻找🔌 Claude Desktop中的图标，以验证服务器是否正在运行。

安装

全球安装

npm install -g x402-claude-mcp

或与npx一起使用

npx x402-claude-mcp

手动配置

注： 我们建议使用 npx x402-claude-mcp setup 而不是手动配置。仅当您喜欢手动设置或需要自定义配置时，才使用此部分。

1.创建配置目录

mkdir -p ~/.x402-claude-mcp

2.创建端点配置

创建 ~/.x402-claude-mcp/endpoints.json:

{
  "wallet": {
    "provider": "cdp-embedded",
    "network": "base",
    "privateKey": "${PRIVATE_KEY}"
  },
  "endpoints": [
    {
      "id": "minifetch_extract_metadata",
      "name": "Extract URL Metadata",
      "url": "https://minifetch.com/api/v1/x402/extract/url-metadata",
      "method": "GET",
      "description": "Fetch and extract HTML metadata from a specified URL. Returns all HTML meta tags, Open Graph tags, Twitter tags, headings, image tags, and response headers. Set includeResponseBody=true to return entire response body as a string. Useful for SEO and AI research projects.",
      "category": "web-scraping",
      "parameters": {
        "type": "object",
        "properties": {
          "url": {
            "type": "string",
            "description": "The URL from which to extract HTML metadata"
          },
          "includeResponseBody": {
            "type": "string",
            "description": "If set to 'true', includes the full HTML response body as a string in the result"
          }
        },
        "required": ["url"]
      },
      "estimatedCost": "$0.01",
      "trusted": true
    }
  ]
}

看 config/endpoints.example.json 对于具有多个端点的完整示例。

3.设置环境变量

创建一个 .env 文件或设置环境变量：

export PRIVATE_KEY="0x..."
export X402_CONFIG_PATH="~/.x402-claude-mcp/endpoints.json"  # Optional, defaults to this
export DEBUG="false"  # Set to "true" for debug logging

4.配置您的MCP客户端

克劳德桌面（macOS）

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "x402-claude-mcp": {
      "command": "npx",
      "args": ["-y", "x402-claude-mcp"],
      "env": {
        "PRIVATE_KEY": "0x...",
        "X402_CONFIG_PATH": "~/.x402-claude-mcp/endpoints.json"
      }
    }
  }
}

克劳德代码

编辑 ~/.claude/settings.json:

{
  "mcp": {
    "x402-claude-mcp": {
      "command": "npx x402-claude-mcp",
      "env": {
        "PRIVATE_KEY": "0x...",
        "X402_CONFIG_PATH": "~/.x402-claude-mcp/endpoints.json"
      }
    }
  }
}

Codex CLI

编辑 ~/.codex/config.toml:

[[mcpServers]]
name = "x402-claude-mcp"
command = "npx"
args = ["x402-claude-mcp"]

[mcpServers.env]
PRIVATE_KEY = "0x..."
X402_CONFIG_PATH = "~/.x402-claude-mcp/endpoints.json"

用法

配置后，LLM代理可以自主使用端点：

User: "Extract metadata from https://example.com and tell me about the page"

Agent: [Calls minifetch_extract_metadata tool]
       [Payment automatically handled via x402]
       [Receives metadata and summarizes]

代理人将：

1. 通过以下方式发现可用工具 tools/list
2. 通过以下方式呼叫端点 tools/call
3. 自动处理402付款响应
4. 将结果返回给用户

生产部署

适用于Node.js应用程序

安装MCP SDK并将x402代理集成到后端：

npm install @modelcontextprotocol/sdk

import { spawn } from 'child_process';
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

// Start MCP server as a child process
const transport = new StdioClientTransport({
  command: 'npx',
  args: ['x402-claude-mcp'],
  env: {
    PRIVATE_KEY: process.env.PRIVATE_KEY,
    X402_CONFIG_PATH: './x402-endpoints.json'
  }
});

const client = new Client({ name: 'my-app', version: '1.0.0' }, {});
await client.connect(transport);

// Call x402-protected endpoints
const result = await client.callTool({
  name: 'minifetch_extract_metadata',
  arguments: { url: 'https://example.com' }
});

console.log('Result:', result.content);
console.log('Transaction:', result.txHash);
console.log('BaseScan:', `https://basescan.org/tx/${result.txHash}`);

配置路径

服务器正在查找 endpoints.json 按照以下顺序：

1. X402_CONFIG_PATH 环境变量（显式路径）
2. ./x402-endpoints.json （项目根）
3. ./config/endpoints.json （配置文件夹）
4. ~/.x402-claude-mcp/endpoints.json （用户主页，回退）

生产最佳实践

部署到生产环境时：

1. 将x402-enpoints.json添加到您的仓库 （无秘密-使用 ${PRIVATE_KEY} 模板）
2. 将PRIVATE_KEY设置为环境变量 在您的部署平台中
3. 将MCP服务器作为子进程运行 从您的后端
4. 监控钱包余额 并设置低USDC警报
5. 使用单独的钱包 适用于开发/测试/生产环境

配置参考

钱包配置

端点配置

环境变量

• PRIVATE_KEY：您的CDP钱包私钥（必填）
• X402_CONFIG_PATH：endpoints.json的路径（默认值： ~/.x402-claude-mcp/endpoints.json)
• DEBUG：启用调试日志记录（默认值： false)

发展

从源代码构建

# Clone the repository
git clone https://github.com/Must-be-Ash/x402-claude-mcp.git
cd x402-claude-mcp

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

项目结构

x402-claude-mcp/
├── src/
│   ├── index.ts              # Main entry point
│   ├── server.ts             # MCP server setup
│   ├── handlers/
│   │   ├── listTools.ts      # tools/list handler
│   │   └── callTool.ts       # tools/call handler
│   ├── registry/
│   │   ├── types.ts          # TypeScript types
│   │   ├── EndpointRegistry.ts
│   │   └── validator.ts      # Config validation
│   ├── payment/
│   │   ├── WalletManager.ts  # CDP wallet
│   │   └── PaymentHandler.ts # x402 integration
│   └── utils/
│       ├── errors.ts         # Error classes
│       ├── logger.ts         # Logging
│       └── retry.ts          # Retry logic
├── config/
│   └── endpoints.example.json
└── package.json

故障排除

服务器未启动

• 检查是否安装了Node.js>=18.0.0： node --version
• 验证PRIVATE_KEY是否设置正确
• 检查配置文件语法： cat ~/.x402-claude-mcp/endpoints.json | jq

端点未显示

• 配置更改后重新启动MCP客户端
• 检查服务器日志是否有错误（设置 DEBUG=true)
• 验证 trusted: true 在端点配置中设置

付款失败

• 确保钱包有足够的USDC余额
• 检查网络是否符合端点要求
• 验证私钥的格式是否正确（0x…）

配置错误

• 验证JSON语法
• 确保所有必填字段都存在
• 检查端点URL是否使用HTTPS
• 验证参数架构是否为有效的JSON架构

安全

信任模型

只有具有以下条件的端点 "trusted": true 可以自主调用。这可以防止：

• 未经授权在未知端点上支出
• 恶意端点注入
• 意外付款执行

设置前仔细检查端点 trusted: true!

私钥安全

✅ 做:

• 将环境变量用于私钥(${PRIVATE_KEY})
• 为开发/暂存/产品使用单独的钱包
• 监控钱包余额并设置警报
• 将私钥保存在安全的秘密管理系统中
• 定期旋转按键

❌ 不要:

• 将私钥提交给git
• endpoints.json中的硬编码私钥
• 在不同应用程序之间共享钱包
• 使用生产钱包进行测试

网络安全

• 所有端点都必须使用HTTPS
• 配置文件应具有受限权限： chmod 600 ~/.x402-claude-mcp/endpoints.json

生产安全检查表

• \[ \] PRIVATE_KEY 设置为环境变量（不在代码中）
• \[ \] endpoints.json 用途 ${PRIVATE_KEY} 模板
• \[\]钱包有足够的美元余额用于预期使用
• \[\]端点已标记 trusted: true 只有在验证之后
• \[\]监控交易日志以发现意外付款
• \[\]设置低USDC余额警报
• \[\]生产前在测试网（基于sepolia）上进行测试
• \[\]针对不同的环境使用单独的钱包

许可证

阿帕奇-2.0

贡献

欢迎投稿！请打开问题或拉取请求。

支持

对于问题和疑问：

• GitHub问题：https://github.com/Must-be-Ash/x402-claude-mcp/issues
• 文档：https://docs.cdp.coinbase.com/x402/

相关项目

• x402协议
• Coinbase开发者平台
• 模型上下文协议

x402克劳德mcp