Elos谷歌搜索MCP服务器
模型上下文协议（MCP）服务器，使用FastMCP和Google自定义搜索API提供Google搜索功能。
特性
- 谷歌搜索：使用Google Custom Search API执行web搜索
- 图像搜索：使用谷歌图片搜索搜索图片
- 网页搜索：专门的网络搜索功能
- 健康监测：内置健康检查和状态监测
- 灵活的身份验证：支持API密钥和服务帐户
- FastMCP集成：基于FastMCP框架构建，实现最佳性能
先决条件
Google API设置
- 谷歌云项目：在中创建项目 谷歌云控制台
- 启用API：启用以下API：
- 自定义搜索API - 自定义搜索引擎API
- 创建自定义搜索引擎:
- 首选 谷歌可编程搜索引擎 - 创建新的搜索引擎 - 注意搜索引擎ID（cx）
- API密钥或服务帐户:
- 选项A：在Google云控制台中创建API密钥 - 选项B：创建服务帐户并下载JSON凭据
当地发展要求
- Python 3.9+
- Docker/Podman
- 访问quay.io注册表
安装
地方发展
- 克隆存储库:
git clone
cd elos-mcp-google-search- 安装依赖项:
pip install -e .- 设置环境变量:
export GOOGLE_API_KEY="your-api-key"
export GOOGLE_CSE_ID="your-search-engine-id"
# OR for service account:
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"- 运行服务器:
python -m elos_google_search_mcp.serverDocker构建
- 塑造形象:
podman build -t elos-google-search-mcp:latest .- 本地测试:
podman run -p 8000:8000 \
-e GOOGLE_API_KEY="your-api-key" \
-e GOOGLE_CSE_ID="your-search-engine-id" \
elos-google-search-mcp:latest部署
推送到Quay.io
- 登录Quay.io:
podman login quay.io- 标记图像:
podman tag elos-google-search-mcp:latest quay.io/elostech/elos-mcp-google-search:latest- 推送图像:
podman push quay.io/elostech/elos-mcp-google-search:latestKubernetes部署
- 更新秘密 使用您的实际凭据：
# Edit kubernetes/elos-google-search-secret.yaml
# Replace placeholder values with actual credentials- 应用配置:
kubectl apply -k kubernetes/- 验证部署:
kubectl get pods -l app=elos-google-search-mcp
kubectl get services -l app=elos-google-search-mcp配置
环境变量
| 变量 | 描述 | 必填 |
|---|---|---|
GOOGLE_API_KEY | 用于身份验证的Google API密钥 | 是（如果使用API密钥） |
GOOGLE_CSE_ID | 自定义搜索引擎ID | 是 |
GOOGLE_APPLICATION_CREDENTIALS | 服务帐户JSON文件的路径 | 是（如果使用服务帐户） |
Kubernetes的秘密
该部署使用Kubernetes secrets来存储敏感信息：
google-api-key：您的Google API密钥google-cse-id：您的自定义搜索引擎IDgoogle-credentials：服务帐户JSON（如果使用服务帐户身份验证）
API终点
MCP服务器提供以下工具：
google_search(query, num_results)
进行一般的谷歌搜索。
参数：
query（str）：搜索查询字符串num_results（int）：结果数量（最多10个）
退货： 包含标题、链接和片段的搜索结果列表
google_search_web(query, num_results)
执行特定于网络的搜索。
参数：
query（str）：搜索查询字符串num_results（int）：结果数量（最多5个）
退货： 网络搜索结果列表
google_search_images(query, num_results)
搜索图像。
参数：
query（str）：搜索查询字符串num_results（int）：结果数量（最多5个）
退货： 图片搜索结果列表
get_search_health()
检查服务器运行状况和配置。
退货： 健康状态和配置信息
使用示例
基本搜索
from elos_google_search_mcp.server import google_search
results = google_search("OpenAI GPT-4", num_results=5)
for result in results:
print(f"Title: {result['title']}")
print(f"Link: {result['link']}")
print(f"Snippet: {result['snippet']}")
print("---")健康检查
from elos_google_search_mcp.server import get_search_health
health = get_search_health()
print(f"Status: {health['status']}")
print(f"Credentials Available: {health['credentials_available']}")故障排除
常见问题
- “没有可用的Google凭据”
- 确保环境变量设置正确 - 检查API密钥或服务帐户文件是否有效
- “GOOGLE_CSE_ID环境变量未设置”
- 设置 GOOGLE_CSE_ID 环境变量 - 验证自定义搜索引擎ID是否正确
- 超过API配额
- 检查您的Google Cloud控制台是否有配额限制 - 考虑升级API计划
- 身份验证错误
- 验证API密钥权限 - 检查服务帐户角色和权限
调试模式
通过设置日志级别启用调试日志记录：
import logging
logging.basicConfig(level=logging.DEBUG)发展
项目结构
elos-mcp-google-search/
├── elos_google_search_mcp/
│ ├── __init__.py
│ └── server.py
├── kubernetes/
│ ├── elos-google-search-deployment.yaml
│ ├── elos-google-search-secret.yaml
│ └── kustomization.yaml
├── Containerfile
├── pyproject.toml
└── README.md添加新工具
要添加新的搜索工具，请使用 @mcp.tool() 装饰师：
@mcp.tool()
def new_search_function(query: str) -> Dict[str, Any]:
"""Description of the new tool."""
# Implementation here
return {"result": "data"}测试
在本地运行测试：
pytest tests/贡献
- 分叉存储库
- 创建要素分支
- 进行更改
- 添加新功能的测试
- 提交拉取请求
许可证
此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。
支持
有关支持和问题：
- 在GitHub存储库中创建问题
- 联系Elos技术团队
更新日志
v0.1.0
- 初始版本
- 谷歌搜索功能
- 图像搜索支持
- 健康监测
- Kubernetes部署支持