AI导哈

付费搜索导航MCP服务器

一个轻量级的模型上下文协议（MCP）服务器，提供对Google Ads和BigQuery数据的访问，用于付费搜索导航分析。

  • by datablogin
  • Python
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 datablogin/PaidSearchNav-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 ```

  2. 创建并激活虚拟环境： ```bash python3-m视频 source.ven/bin/activate#在Windows上：.venv\Scripts\activate ```

  3. 安装依赖项： ```bash pip安装-e“.[dev]” ```

  4. 配置环境变量： ```bash cp.env.example.env

    使用您的凭据编辑.env

    ```

  5. 运行测试： ```bash pytest测试/test_server.py-v ```

  6. 启动MCP服务器： ```bash python-m paidsearchnav_mcp.server ```

Docker部署

  1. 使用Docker Compose构建和运行： ```bash docker组成-up-d ```

  2. 检查健康状况： ```bash 卷曲http://localhost:8080/health ```

  3. 查看日志： ```bash docker编写日志-f mcp服务器 ```

配置

环境变量

变量 描述 必填 默认
`GOOGLE_ADS_DEVELOPER_TOKEN` GOOGLE ADS API开发者令牌 是 -
“GOOGLE_ADS_CLIENT_ID” OAuth客户端ID 是 -
`GOOGLE_ADS_CLIENT_SECRET` OAuth客户端机密 是 -
`GOOGLE_ADS_REFRESH_TOKEN` OAuth刷新令牌 是 -
`GOOGLE_ADS_LOGIN_CUSTOMER_ID` 经理帐户ID（无破折号） 是 -
`GOOGLE_ADS_API_VERSION` GOOGLE ADS API版本 否 `v17`
`GOOGLE_APPLICATION_CREDENTIALS` GCP服务帐户JSON路径 可选 -
`GCP_PROJECT_ID` BigQuery的GCP项目ID 可选 -
`REDIS_URL` REDIS连接URL 否 `redis://localhost:6379/0`
“REDIS_TTL” 缓存TTL（秒） 否 “3600”
“环境” 环境名称（开发/生产） 否 “开发”

有关获取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

相关 MCP