Serper API MCP服务器
这是一个MCP（模型上下文协议）服务器，通过承载令牌访问Serper API API来提供认证。它使人工智能代理和LLM能够通过标准化工具与Serper API进行交互。
特性
- 🔧 MCP协议：基于模型上下文协议构建，实现无缝的人工智能集成
- 🌐 API完全访问：提供用于与Serper API端点交互的工具
- 🔐 安全认证：支持通过Bearer令牌进行API密钥身份验证
- 💳 HTTP 402支付协议：双模式操作（认证或付费访问）
- 🔗 D402集成：使用traia_iatp.d402进行区块链支付验证
- 🐳 Docker支持：使用Docker和Docker Compose轻松部署
- ⚡ 异步操作：内置FastMCP，实现高效异步处理
API 文档
- Serper API网站:
- ****: https://serper.dev/docs
可用工具
此服务器提供以下工具：
example_tool：占位符工具（待实施）
*注：更换 example_tool 使用基于文档的实际Serper API API工具。*
安装
使用Docker（推荐）
- 克隆此存储库：
git clone https://github.com/Traia-IO/serper-api-mcp-server.git
cd serper-api-mcp-server- 设置API密钥：
export SERPER_API_KEY="your-api-key-here"- 使用Docker运行：
./run_local_docker.sh使用Docker Compose
- 创建一个
.env使用您的配置文件：
服务器的内部API密钥（用于支付模式）
SERPER_API_KEY=您所在的位置
服务器支付地址（适用于HTTP 402协议）
服务器地址=0x123456789012345678901234567890123467890
操作员密钥（用于签署结算证明）
MCP_OPERATOR_PRIVATE_KEY=0x1234567890abcdef。.. MCP_OPERATOR_ADDRESS=0x9876543210fedcba。..
可选：测试模式（跳过本地开发的结算）
D402_TESTING_MODE=假 端口=8000
2. Start the server:docker-compose up
### 手动安装
1. 使用安装依赖项 `uv`:
uv pip install -e .
1. 运行服务器：
SERPER_API_KEY=“your-API-KEY-here”uv运行python-m服务器
Usage
Health Check
Test if the server is running:
python mcp_health_check.py使用CrewAI
from traia_iatp.mcp.traia_mcp_adapter import create_mcp_adapter_with_auth
# Connect with authentication
with create_mcp_adapter_with_auth(
url="http://localhost:8000/mcp/",
api_key="your-api-key"
) as tools:
# Use the tools
for tool in tools:
print(f"Available tool: {tool.name}")
# Example usage
result = await tool.example_tool(query="test")
print(result)身份验证和支付（HTTP 402协议）
此服务器支持 两种操作模式:
模式1：身份验证访问（免费）
拥有自己的Serper API API密钥的客户端可以免费使用服务器：
# Request with client's API key
curl -X POST http://localhost:8000/mcp \
-H "Authorization: Bearer CLIENT_SERPER_API_KEY" \
-H "Content-Type: application/json" \
-d '{"method":"tools/call","params":{"name":"example_tool","arguments":{"query":"test"}}}'流动:
- 客户提供其Serper API API密钥
- 服务器使用客户端的API密钥调用Serper API API
- 无需付款
- 客户直接向Serper API付款
模式2：需要付款（付费访问）
没有API密钥的客户端可以通过HTTP 402协议按次付费：
# Request with payment proof (x402/d402 protocol)
curl -X POST http://localhost:8000/mcp \
-H "X-PAYMENT: " \
-H "Content-Type: application/json" \
-d '{"method":"tools/call","params":{"name":"example_tool","arguments":{"query":"test"}}}'流动:
- 客户在未付款的情况下提出初始请求
- 服务器返回带有支付要求（令牌、网络、金额）的HTTP 402
- 客户端创建EIP-3009 transferWithAuthorization付款签名
- 客户端base64对支付进行编码，并在X-payment标头中发送
- 服务器通过traia_iatp.d402.mcp_middleware验证付款
- 服务器使用其内部Serper API API密钥调用API
- 客户端收到结果
D402协议详细信息
此服务器使用 训练活动d402 支付验证模块：
- 支付方式：EIP-3009转移授权（无气体）
- 支持的代币：USDC、TRAIA或任何ERC20代币
- 默认价格：每个请求0.001美元（可通过以下方式配置
DEFAULT_PRICE_USD) - 网络：基础色派、色派、Polygon等。
- 引导者：d402.org（公共）或定制服务商
支付模式的环境变量
# Required
SERPER_API_KEY=your_internal_serper-api_api_key # Server's API key (for payment mode)
SERVER_ADDRESS=0x1234567890123456789012345678901234567890 # Server's payment address
# Required for Settlement (Production)
MCP_OPERATOR_PRIVATE_KEY=0x1234... # Private key for signing settlement attestations
MCP_OPERATOR_ADDRESS=0x5678... # Operator's public address (for verification)
# Optional
D402_FACILITATOR_URL=https://facilitator.d402.net # Facilitator service URL
D402_FACILITATOR_API_KEY=your_key # For private facilitator
D402_TESTING_MODE=false # Set to 'true' for local testing without settlement操作员密钥:
- MCP_OPERATOR_PRIVATE_KEY：用于签署结算证明（服务完成证明）
- MCP操作员地址：私钥对应的公共地址
- 需要通过IATP结算层进行链上结算
- 可以与SERVER_ADDRESS相同，也可以是单独的运算符键
关于每个端点配置的说明: 每个端点的支付要求（令牌地址、网络、价格）都嵌入在工具代码中。 它们来自生成服务器时的端点配置。
运作原理
- 客户决策:
- Serper API API有密钥吗？ → 模式1（已验证） - 没有API密钥但愿意支付？ → 模式2（付款）
- 服务器响应:
- 模式1：使用客户端的API密钥（客户端免费） - 模式2：使用服务器的API密钥（客户端向服务器付款）
- 商业模式:
- 模式1：无收入（转嫁） - 模式2：按次付费收入（将服务器的API订阅货币化）
发展
测试服务器
- 在本地启动服务器
- 运行健康检查：
python mcp_health_check.py - 使用CrewAI适配器测试单个工具
添加新工具
要添加新工具，请编辑 server.py 以及：
- 为Serper API端点创建API客户端函数
- 添加
@mcp.tool()装饰功能 - 使用新工具更新此README
- 更新
deployment_params.json工具名称位于功能数组中
部署
部署配置
这 deployment_params.json 文件包含此MCP服务器的部署配置：
{
"github_url": "https://github.com/Traia-IO/serper-api-mcp-server",
"mcp_server": {
"name": "serper-api-mcp",
"description": "Serper internet data api",
"server_type": "streamable-http",
"requires_api_key": true,
"api_key_header": "Authorization",
"capabilities": [
// List all implemented tool names here
"example_tool"
]
},
"deployment_method": "cloud_run",
"gcp_project_id": "traia-mcp-servers",
"gcp_region": "us-central1",
"tags": ["serper api", "api"],
"ref": "main"
}重要：始终更新 capabilities 添加或删除工具时使用数组！
谷歌云运行
此服务器旨在部署在Google Cloud Run上。部署将：
- 从Dockerfile构建一个容器
- 使用指定配置部署到Cloud Run
- 暴露
/mcp客户端连接的端点
环境变量
PORT：服务器端口（默认值：8000）STAGE：环境阶段（默认：MAINNET，选项：MAINNET、TESTNET）LOG_LEVEL：日志记录级别（默认值：INFO）SERPER_API_KEY：您的Serper API API密钥（必需）
故障排除
- 服务器未启动：使用以下命令检查Docker日志
docker logs - 身份验证错误：确保在环境中正确设置了API密钥
- API错误：验证您的API密钥是否具有必要的权限3。 工具错误：检查服务器日志以获取详细的错误消息
贡献
- 分叉存储库
- 创建要素分支
- 实施新工具或改进
- 更新README和deployment_params.json
- 提交拉取请求