内容
# 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 提供支持**
MCP 市场