Places-x402-Mcp

# X402 Places MCP Server **Claude Desktop 集成** Google Places API，支持自动 x402 微支付。 > 🔒 **零燃气费**：客户每次搜索支付 $0.01 USDC，促进者支付燃气费 > 🤖 **原生 AI**：为 Claude Desktop 和 AI 代理构建 > ⚡ **即时支付**：EIP-712 签名，亚秒级处理 > 🗺️ **实时数据**：实时 Google Places API 集成 ## 这是什么？ 这是一个 **模型上下文协议 (MCP) 服务器**，允许 Claude Desktop 使用 **x402 微支付** 搜索 Google Places。您每次搜索支付 $0.01 USDC，且没有燃气费。 ### 主要特性 - ✅ **实时数据**：以 $0.01 USDC 获取实时 Google Places 结果 - ✅ **无燃气费**：促进者支付所有燃气费 - ✅ **安全**：私钥保持本地，EIP-712 签名 - ✅ **快速**：亚秒级支付处理 ## 快速开始 ### 1. 克隆代码库 ```bash git clone https://github.com/yourusername/places-x402-mcp.git cd places-x402-mcp pnpm install ``` ### 2. 配置 Claude Desktop 在您的 Claude Desktop 配置中添加： - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` **配置**： ```json { "mcpServers": { "places-x402": { "command": "pnpm", "args": [ "--silent", "-C", "/absolute/path/to/places-x402-mcp", "dev" ], "env": { "PRIVATE_KEY": "0xYourWalletPrivateKeyWithUSDC", "RESOURCE_SERVER_URL": "https://places-api.x402hub.xyz", "ENDPOINT_PATH": "/api/places/text-search" } } } } ``` **重要**：将 `/absolute/path/to/places-x402-mcp` 替换为您克隆代码库的实际路径。 ### 3. 重启 Claude Desktop 关闭并重新打开 Claude Desktop 以加载 MCP 服务器。 ### 4. 尝试一下 问 Claude： - "在旧金山找咖啡店" - "在37.7749,-122.4194附近搜索餐馆，范围2公里" - "在波特兰市中心找加油站" ## 需求 1. **钱包私钥**：在 Base 网络上有 USDC 2. **USDC 余额**：建议至少 $0.10 USDC 3. **Base 网络**：主网 (生产) 或 Sepolia (测试) ### 如何在 Base 上获取 USDC **选项 1：从以太坊桥接** 1. 访问 [Base Bridge](https://bridge.base.org/) 2. 连接您的钱包 3. 从以太坊主网桥接 USDC 到 Base **选项 2：在 Base 上购买** 1. 使用 [Coinbase](https://www.coinbase.com/) 购买 USDC 2. 提现到您的 Base 网络地址 **选项 3：测试网 (Base Sepolia)** 1. 从 [Base Sepolia Faucet](https://www.alchemy.com/faucets/base-sepolia) 获取测试 ETH 2. 在 Base Sepolia 上兑换测试 USDC ## 可用工具 MCP 服务器提供 3 个工具供 Claude 使用： ### 1. search_places 使用 Google Places API 搜索地点。 **参数**： - `query` (必需)：搜索词（例如，“比萨餐厅”） - `location` (可选)：经纬度格式（例如，“37.7749,-122.4194”） - `radius` (可选)：搜索半径（最大 50000 米） **示例**： ``` Claude: 在西雅图市中心找咖啡店 ``` ### 2. get_service_info 获取 x402 服务信息和支付要求。 **示例**： ``` Claude: Places API 的支付要求是什么？ ``` ### 3. check_health 检查 Places API 服务的健康状态。 **示例**： ``` Claude: 检查 Places API 是否正常工作 ``` ## X402 支付如何工作 1. **Claude 发送搜索请求** → MCP 服务器 2. **MCP 服务器创建 EIP-712 签名** → 您的钱包本地签名 3. **签名发送到 API** → 您无需支付燃气费 4. **促进者验证并执行** → 支付燃气费 5. **USDC 转账** → 从您的钱包转出 $0.01 到 API 6. **Google Places 结果** → 返回给 Claude **安全注意事项**： - ✅ 私钥保持本地（从不发送到任何地方） - ✅ EIP-712 签名在加密上是安全的 - ✅ 每个签名为一次性使用（防重放） - ✅ 促进者是可信的第三方（Coinbase CDP） ## 生产 API 详情 - **URL**: https://places-api.x402hub.xyz - **网络**: Base 主网 - **代币**: USDC - **价格**: 每次搜索 $0.01 - **协议**: x402 v1.0 - **促进者**: CDP x402 促进者（Coinbase） ## 开发 ### 项目结构 ``` places-x402-mcp/ ├── index.ts # 主 MCP 服务器实现 ├── package.json # NPM 包配置 ├── tsconfig.json # TypeScript 配置 └── README.md # 本文件 ``` ## 故障排除 ### MCP 服务器未加载 1. 检查 Claude Desktop 配置文件语法（有效的 JSON） 2. 验证文件路径是否正确 3. 完全重启 Claude Desktop 4. 检查 Claude Desktop 日志以获取错误信息 ### 支付失败 1. **检查 USDC 余额**：需要至少 $0.01 USDC 2. **验证网络**：必须是 Base 主网（不是以太坊） 3. **检查钱包**：私钥必须有效并以 `0x` 开头 4. **重启 Claude Desktop**：在任何配置更改后 ### API 错误 1. **检查服务状态**： https://places-api.x402hub.xyz/health 2. **验证连接性**：测试互联网连接 3. **检查 API URL**：在配置中必须正确 4. **再试一次**：临时网络问题 ## 安全最佳实践 ### 私钥安全 - ⚠️ **绝不要分享** 您的私钥 - ⚠️ **使用专用钱包**，资金尽量少 - ⚠️ **定期更换密钥** - ⚠️ **保持备份** 安全 ### 推荐的钱包设置 1. 创建专门用于 MCP 支付的新钱包 2. 仅存入 $1-5 USDC 3. 不要在此钱包中存储大量资金 4. 定期监控交易 ## 支持与资源 - **生产 API**: https://places-api.x402hub.xyz - **X402 文档**: https://docs.cdp.coinbase.com/x402/ - **MCP 协议**: https://modelcontextprotocol.io/ - **GitHub 问题**: https://github.com/yourusername/places-x402-mcp/issues ## 许可证 MIT 许可证 - 详见 LICENSE 文件 ## 相关项目 - [x402 Protocol](https://x402.org/) - HTTP 402 微支付标准 - [x402-axios](https://www.npmjs.com/package/x402-axios) - 支持支付的 Axios - [模型上下文协议](https://modelcontextprotocol.io/) - AI 集成标准 --- **为 Claude Desktop 精心构建 ❤️** **由 x402 Protocol 提供支持**