Paid Search Nav MCP

PaidSearchNav MCP服务器

轻量级 模型上下文协议（MCP） 服务器为PaidSearchNav分析器提供对Google广告和BigQuery数据的访问。

这是PaidSearchNav重构工作的一部分，旨在将数据连接（MCP服务器）与分析逻辑（Claude Skills）分离。看 thoughts/shared/research/2025-11-12-mcp-kills重构策略.md 了解更多详情。

备注：原始的单片PaidSearchNav应用程序已存档至 archive/。参见 存档/README.md 作为参考资料。

概述

PaidSearchNav MCP服务器是 最低限度的集装箱化服务 （约200MB Docker镜像），提供：

• ✅ 通过MCP工具访问Google Ads API
• ✅ BigQuery查询执行
• ✅ 活动、关键字和搜索词数据检索
• ✅ 地理性能数据
• ✅ 负面关键字冲突检测
• ✅ 新增：用于服务器端分析的编排工具 （第2.5阶段-2/5完成）
• ✅ 基于Redis的性能缓存

建筑

第2.5阶段双层设计 （解决了上下文窗口的限制）：

\\\ ┌─────────────────────────────────────────────────────────────┐ │ 轻量级技能的Claude桌面│ │ - 技能是20-50行提示（最少上下文使用）│ │ - 呼叫编排工具（非原始数据工具）│ │ - 格式化结果以供用户显示│ └─────────────────────┬───────────────────────────────────────┘ │ MCP协议 ▼ ┌─────────────────────────────────────────────────────────────┐ │ PaidSearchNav MCP服务器（Docker）-配置层│ │ │ │ 第1层：编排工具（阶段2.5-4/5完成✅)│ │ ├─ analyze_keyword_match_types（）→总结+前10名✅│ │ ├─ analyze_search_term_wast（）→总结+前10名✅│ │ ├─ 分析_负面_冲突（）→总结+前10名✅│ │ ├─ analyze_geo_performance（）→总结+前10名⚠️│ │ └─ analyze_pmax_分解（）→总结+前10名✅│ │ │ │ 第2层：数据检索工具（完整）│ │ ├─ get_keywords（）→原始数据（分页）│ │ ├─ get_search_terms（）→原始数据（分页）│ │ ├─ get_campaigns（）→原始数据│ │ ├─ get_negative_keywords（）→原始数据│ │ ├─ get_geo_performance（）→原始数据│ │ └─ query_bigquery（）→原始数据│ │ │ │ 基础设施：│ │ - Redis缓存（基于TTL）│ │ - Google Ads API客户端│ │ - BigQuery客户端│ │ - 错误处理和速率限制│ └─────────────────────────────────────────────────────────────┘ \\\

关键创新：服务器执行分析并返回精简摘要（11-34行），而不是原始数据（数千行），消除了Claude Desktop的上下文窗口限制。

快速开始

先决条件

• Python 3.12+
• Docker和Docker Compose（用于容器化部署）
• Google Ads API证书
• BigQuery的GCP服务帐户（可选）

地方发展设置

1. 克隆存储库：

\\\bash 克隆 cd PaidSearchNav MCP \\\

1. 创建并激活虚拟环境：

\\\bash python3-m视频 source.ven/bin/activate#在Windows上：.venv\\Scripts\\activate \\\

1. 安装依赖项：

\\\bash pip安装-e“.\[dev\]” \\\

1. 配置环境变量：

\\\`bash cp.env.example.env

# 使用您的凭据编辑.env

\\\`

1. 运行测试：

\\\bash pytest测试/test_server.py-v \\\

1. 启动MCP服务器：

\\\bash python-m paidsearchnav_mcp.server \\\

Docker部署

1. 使用Docker Compose构建和运行：

\\\bash docker组成-up-d \\\

1. 检查健康状况：

\\\bash 卷曲http://localhost:8080/health \\\

1. 查看日志：

\\\bash docker编写日志-f mcp服务器 \\\

配置

环境变量

有关获取Google Ads API证书的详细说明，请参阅 docs/GOOGLE_ADS_SETUP.md.

快速测试

配置凭据后，您可以快速测试MCP服务器功能。

测试1：验证服务器运行状况

启动服务器并检查运行状况终结点：

\\\`bash

终端1：启动MCP服务器

python-m paidsearchnav_mcp.server

终端2：检查运行状况（如果HTTP端点可用）

卷曲http://localhost:8080/health \\\`

测试2：配置MCP客户端

将服务器添加到Claude桌面配置中（macOS上的\~/Library/ApplicationSupport/Claude/Claude_Desktop_config.json \）：

\\\`json {

“Redis URL”：“redis://localhost:6379/0" } } } } \\\`

或者使用\.env\文件中的环境变量：

\\\json { “mcpServers”：{ “paidsearchnav”：{ “command”：“python”， “args”：\[“-m”，“paidsearchnav_mcp.server”\]， “cwd”：“/path/to/PaidSearchNav MCP” } } } \\\

测试3：查询样本数据

重新启动Claude Desktop并使用以下示例查询进行测试：

为客户获取活动： \\\ 使用get_campaigns工具获取客户ID 1234567890的活动 \\\

获取搜索词： \\\ 使用get_search_terms工具获取客户1234567890的搜索词数据 从过去30天开始 \\\

获取匹配类型的关键字： \\\ 使用get_keywords工具检索客户1234567890的所有关键字， 显示比赛类型和质量分数 \\\

测试4：验证Redis缓存（可选）

如果你已经配置了Redis缓存，请验证它是否正常工作：

1.检查Redis连接：

\\\bash redis-cli-ping#应返回PONG \\\

2.进行两次相同的查询：

\\\ 使用相同的参数两次使用get_campaigns工具： 客户编号：1234567890，日期：2024年1月1日至2024年01月31日 \\\

3.检查缓存命中日志：

\\\ 第一个请求：“缓存未命中的活动查询：客户=1234567890” 第二个请求：“活动查询的缓存命中率：客户=1234567890” \\\

4.验证性能改进：

• 第一次请求：约500-1000ms（API调用）
• 第二个请求：~10-50ms（缓存命中）

缓存TTL： 根据数据类型，结果将缓存1-4小时（可通过.env中的REDIS_TTL配置）

测试5：验证数据是否返回

成功的应对措施应包括：

• 活动：活动ID、名称、状态、预算、目标设置
• 搜索词：查询文本、匹配类型、点击次数、展示次数、成本、转化率
• 关键词：关键字文本、匹配类型、质量分数、绩效指标

预期输出示例： \\\json { “活动”：\[ { “id”：“1234567890”， “name”：“品牌活动”， “状态”：“已启用”， “预算”：100.0， “投标策略”：“最大版本” } \] } \\\

测试5:Docker环境测试

测试容器化设置：

\\\`bash

使用docker compose启动服务

docker组成-up-d

检查服务器日志

docker编写日志-f mcp服务器

测试健康终点

卷曲http://localhost:8080/health

验证Redis是否正在运行

docker编写执行redis-redis-cli-ping

应返回：PONG

\\\`

快速测试故障排除

如果您遇到问题：

1. 身份验证错误：验证\.env\中的所有凭据是否正确
2. 未返回数据：检查客户ID是否有可访问的活动
3. 连接超时：确保Redis正在运行（\docker compose ps\）
4. 权限错误：验证您的OAuth令牌具有正确的作用域

看 docs/GOOGLE_ADS_SETUP.md 了解详细的故障排除步骤。

MCP工具

服务器公开了以下MCP工具：

编排工具（第2.5阶段-完成✅)

新：五个服务器端分析器，返回紧凑的摘要（\<100行）而不是原始数据：

• \分析搜索条款浪费\ ✅ - 识别浪费的支出并推荐负面关键词（生产就绪）

- 已识别的储蓄每月1553.43美元（来自测试账户） - 演出：18.24秒，34行输出

• \分析负面冲突\ ✅ - 检测阻止正关键字的负关键字（生产就绪）

- 价值：收入保护，检测到12282个冲突 - 演出：19.38秒，34行输出

• \analyze_pmax_同类相食\ ✅ - 确定PMax/搜索重叠（生产就绪）

- 价值：ROI优化 - 演出：25.47秒，11线输出

• \分析关键字匹配类型\ ✅ - 推荐匹配类型优化（生产就绪）

- 已识别的储蓄：20.80美元/月（来自测试账户） - 演出：27.35秒，15行输出

• \分析geo性能\ ⚠️ - 建议地域投标调整（正在修复-第20期）

- 状态：GAQL查询已修复，ROAS计算错误已得到解决 - 预期：24小时内准备就绪

状态：4/5生产就绪（80%），1个修复正在进行中

展示商业价值：从单个测试账户中确定的优化机会为1574.23美元/月

建筑成就：解决了上下文窗口问题-响应大小减少了95%（800行→ 23 线路平均值）

看 第2.5阶段竣工报告 进行详细分析。

数据检索工具（Google Ads API）

• \get_search_terms\ -使用性能指标获取搜索词数据
• \获取关键字\ -使用匹配类型和质量分数检索关键字
• \get_campaigns\ -获取活动设置和绩效数据
• \get_negative_keywords\ -获取负面关键字和共享列表
• \get_geo_performance\ -按地点划分的地理表现

BigQuery工具

• \query_bigquery\ -对BigQuery执行自定义SQL查询

MCP资源

• \resource://health\ -服务器健康状态和配置
• \resource://config\ -功能可用性和设置

发展

项目结构

\\\ PaidSearchNav MCP/ ├── src/ │ └── paidsearchnav_mcp/ │ ├── __初始化__南美国家巴拉圭的缩写（Paraguay） │ ├── server.py#MCP服务器入口点 │ ├── 分析器/#新增：编排层（第2.5阶段） │ │ ├── base.py#BaseAnalyzer+分析摘要 │ │ ├── keyword_match.py#关键字匹配分析器 │ │ ├── search_term_waste.py#SearchTermWasteAnalyzer✅ │ │ ├── negative_conconflicts.py#负冲突分析器✅ │ │ ├── geo_performance.py#地理性能分析器 │ │ └── pmax_cannibalization.py#PMaxCannibalizationAnalyzer │ ├── 客户端/#API客户端 │ │ ├── google/#谷歌广告客户端 │ │ ├── bigquery/#bigquery客户端 │ │ └── ga4/#ga4客户端 │ ├── 模型/#数据模型 │ └── 数据提供者/#数据提供者接口 ├── 测试/ │ ├── test_server.py │ ├── test_analyzers.py#新增：分析仪单元测试 │ ├── test_orchestration_tools.py#新增：编排工具测试 │ └── bugs/#新：Bug复制测试 ├── 脚本/ │ ├── test_orchestration_direct.py#新增：集成测试 │ └── test_oarchstration_integration.py ├── docs/ │ └── bugs/#新增：Bug报告 │ ├── README.md │ ├── 2025-11-27-关键字-无数据.md │ ├── 2025-11-27-地理性能-质量错误.md │ └── 2025-11-27-pmax--分析仪-slow.md ├── Dockerfile ├── docker-compose.yml ├── pyproject.toml └── README.md \\\

运行测试

\\\`bash

具体测试文件（目前推荐）

pytest测试/test_server.py-v

覆盖范围

pytest tests/test_server.py--cov=paidsearchnav_mcp--cov report=html \\\`

代码质量

\\\`bash

格式代码

ruff格式src/

棉绒

拉夫检查src/

类型检查

mypy src/ \\\`

部署

Docker镜像大小

生产Docker镜像优化为约200MB（原始PaidSearchNav应用程序为1.5GB）：

• Python 3.12-slim基础镜像
• 只有8个核心依赖项
• 无数据库或web框架开销

许可证

\[您的许可证在这里\]

支持

对于问题和疑问：

• GitHub问题：https://github.com/datablogin/PaidSearchNav-MCP/issues
• 文档：https://github.com/datablogin/PaidSearchNav