AgencyAnalytics管理服务器

代理分析MCP服务器

蟒蛇 模型上下文协议（MCP） 服务器 代理分析 这使人工智能助手能够通过自然语言管理活动、用户、反向链接、关键字和SEO排名。

适用于： Claude Desktop、Claude Code、Cursor、Windsurf、Cline、Continue、Zed和任何兼容MCP的客户端。

由您呈现 奥舍尔数字 -专业的人工智能顾问帮助企业利用人工智能的力量。

特性

• 21工具 覆盖整个AgentAnalytics API表面
• 活动管理 -创建、读取、更新和删除活动（客户端）
• 用户管理 -为平台用户提供完整的CRUD操作，包括角色和访问控制
• 反向链接跟踪 -使用域/页面权限管理每个活动的自定义反向链接
• SEO排名 -在谷歌、谷歌移动、谷歌地点和必应上拉取关键字级别和活动级别的排名数据
• 关键字监控 -读取每个广告系列的跟踪关键字
• 竞争对手跟踪 -将竞争对手的URL添加到广告系列中以进行排名比较
• SSO登录授权 -为客户端门户访问生成一次性登录令牌
• 标签管理 -创建组织标签

先决条件

• Python 3.10+
• 紫外线 （推荐）或pip
• 上的AgencyAnalytics帐户 卓越计划 （需要API访问权限）
• API密钥（仅限管理员用户）

获取API密钥

1. 以管理员身份登录AgencyAnalytics 管理员 用户
2. 首选 管理员设置>公司详细信息
3. 您的API密钥位于页面的右下角

备注：只有帐户管理员用户才能访问API密钥。API访问仅适用于卓越理财计划。API密钥未过期。

安装

1.克隆存储库

git clone https://github.com/osherai/mcp-agencyanalytics-python.git
cd mcp-agencyanalytics-python

2.安装依赖项

使用紫外线（推荐）：

uv venv && uv pip install -e .

或者使用pip：

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -e .

3.配置凭据

复制示例环境文件并添加您的API密钥：

cp .env.example .env

编辑 .env:

AGENCYANALYTICS_API_KEY=your_api_key_here

4.测试连接

uv run agencyanalytics-mcp

服务器应无错误启动（它将等待stdin上的输入）。

客户端配置

此MCP服务器可与任何兼容MCP的客户端配合使用。以下是常见客户端的设置说明。

备注：替换 /path/to/mcp-agencyanalytics-python 在下面的所有示例中使用您的实际安装路径。

克劳德桌面版

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "agencyanalytics": {
      "command": "/path/to/mcp-agencyanalytics-python/.venv/bin/python",
      "args": ["-m", "agencyanalytics_mcp.server"],
      "cwd": "/path/to/mcp-agencyanalytics-python"
    }
  }
}

重新启动Claude Desktop（完全退出并重新打开）以使更改生效。

克劳德代码（CLI）

使用Claude Code CLI添加服务器：

claude mcp add agencyanalytics \
  -e AGENCYANALYTICS_API_KEY=your_api_key_here \
  -- /path/to/mcp-agencyanalytics-python/.venv/bin/python -m agencyanalytics_mcp.server

或添加到您的 ~/.claude/settings.json:

{
  "mcpServers": {
    "agencyanalytics": {
      "command": "/path/to/mcp-agencyanalytics-python/.venv/bin/python",
      "args": ["-m", "agencyanalytics_mcp.server"],
      "cwd": "/path/to/mcp-agencyanalytics-python"
    }
  }
}

光标

添加到光标MCP配置中：

macOS: ~/.cursor/mcp.json 视窗: %USERPROFILE%\.cursor\mcp.json

{
  "mcpServers": {
    "agencyanalytics": {
      "command": "/path/to/mcp-agencyanalytics-python/.venv/bin/python",
      "args": ["-m", "agencyanalytics_mcp.server"],
      "cwd": "/path/to/mcp-agencyanalytics-python"
    }
  }
}

重新启动Cursor以使更改生效。

风帆冲浪（Codeium）

添加到您的Windsurf MCP配置中：

macOS: ~/.codeium/windsurf/mcp_config.json 视窗: %USERPROFILE%\.codeium\windsurf\mcp_config.json

{
  "mcpServers": {
    "agencyanalytics": {
      "command": "/path/to/mcp-agencyanalytics-python/.venv/bin/python",
      "args": ["-m", "agencyanalytics_mcp.server"],
      "cwd": "/path/to/mcp-agencyanalytics-python"
    }
  }
}

重新启动Windsurf以使更改生效。

带有Cline扩展的VS代码

添加到您的Cline MCP设置中：

macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json 视窗: %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json

{
  "mcpServers": {
    "agencyanalytics": {
      "command": "/path/to/mcp-agencyanalytics-python/.venv/bin/python",
      "args": ["-m", "agencyanalytics_mcp.server"],
      "cwd": "/path/to/mcp-agencyanalytics-python"
    }
  }
}

带有Continue扩展名的VS代码

添加到您的继续配置 ~/.continue/config.json:

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "/path/to/mcp-agencyanalytics-python/.venv/bin/python",
          "args": ["-m", "agencyanalytics_mcp.server"],
          "cwd": "/path/to/mcp-agencyanalytics-python"
        }
      }
    ]
  }
}

Zed编辑

添加到您的Zed设置 ~/.config/zed/settings.json:

{
  "context_servers": {
    "agencyanalytics": {
      "command": {
        "path": "/path/to/mcp-agencyanalytics-python/.venv/bin/python",
        "args": ["-m", "agencyanalytics_mcp.server"]
      },
      "settings": {}
    }
  }
}

查询示例

配置后，您可以就AgencyAnalytics数据提出自然语言问题：

• “列出我的所有活动”
• “显示广告系列123的关键字排名”
• “为创建新的客户端用户jane@acme.com"
• “Acme Corp活动有哪些反向链接？”
• “为用户456生成SSO登录链接”
• “将竞争对手example.com添加到活动123”

工具参考

活动工具

活动在AgentAnalytics UI（更名为2025年2月）中被称为“客户”，但API仍然使用“活动”一词。

list_campaigns

按页码列出活动。

get_campaign

按ID获取单个活动。

create_campaign

创建新活动。

update_campaign

更新现有活动。

delete_campaign

按ID删除活动。

用户工具

list_users

列出所有分页的平台用户。

返回的字段： id, date_created, date_modified, email, username, first_name, last_name, role, campaign_access, status, account_id, campaign_id

get_user

按ID获取单个用户。

create_user

创建新用户。

update_user

更新现有用户。

delete_user

按ID删除用户。

反向链接工具

list_backlinks

列出带有可选活动过滤的反向链接。

返回的字段： id, title, status, date_created, date_published, url, link_type, target_anchor, target_url, notes, campaign_id, domain_authority, page_authority

create_backlink

创建新的反向链接。

update_backlink

更新现有的反向链接。

delete_backlink

按ID删除反向链接。

关键字和排名工具

list_keywords

列出活动的跟踪关键字。关键字一次只能查询一个活动。

get_keyword_rankings

获取活动的关键字级别排名数据。返回Google、Google Mobile、Google Places和Bing的位置，包括更改跟踪、SERP URL和每月搜索量。

返回的字段包括： keywordId, keywordPhrase, googleRanking, googleRankingChange, googleRankingUrl, googleMobileRanking, googleMobileRankingChange, googlePlacesRanking, bingRanking, bingRankingChange, localMonthlySearches以及更多。

get_campaign_rankings

获取一段时间内的活动排名汇总数据。返回历史趋势和排名分布（位置1-3、4-10、11-20、21-50、51+）以及竞争对手数据。

其他工具

create_competitor

将竞争对手URL添加到活动中以进行排名比较。

create_tag

创建组织标签。

create_login_grant

为用户生成一次性SSO登录URL。该令牌允许在没有密码的情况下登录AgencyAnalytics。可用于嵌入报告或构建自定义登录页面。

退货： token, login_url, time, user_id, origin_user_id

建筑

代理分析API的工作原理

与传统的REST API不同，AgentAnalytics API使用 单个POST端点 (https://apirequest.app/query)对于所有操作。每个请求都包含一个JSON正文，指定：

• provider -总是 "agency-analytics-v2"
• asset -资源类型(campaign, user, backlink, keyword等等）
• operation -行动(create, read, update, delete)
• fields -返回哪些字段（用于读取操作）
• rows -用于创建/更新/删除操作的数据
• offset / limit -分页

身份验证使用空用户名和API密钥作为密码的HTTP基本身份验证。

API资产和支持的操作

API限制

AgentyAnalytics API专为 平台管理与SEO数据检索确实如此 不 提供以下访问权限：

• 第三方集成数据（谷歌广告、脸书广告、GA4、社交媒体等）
• 报告生成或导出
• 仪表板/小部件数据
• PPC、电子邮件营销或电子商务指标

虽然AgencyAnalytics在其UI中连接到90多个集成，但这些数据都不会通过API公开。

请求的生命周期

MCP Tool Call
  -> AgencyAnalyticsClient._build_payload()  (construct JSON body)
  -> AgencyAnalyticsClient._request()         (POST to https://apirequest.app/query)
  -> Parse response { metadata, data }
  -> format_response()                        (JSON with summary)
  -> Return to MCP client

项目结构

mcp-agencyanalytics-python/
├── pyproject.toml                  # Project config, dependencies, entry point
├── .env.example                    # Environment variables template
├── .gitignore                      # Python/IDE/OS ignores
├── README.md                       # This file
├── src/
│   └── agencyanalytics_mcp/
│       ├── __init__.py             # Package version
│       ├── server.py               # MCP server with 21 tool definitions
│       ├── config.py               # Dataclass config loaded from environment
│       └── client.py               # AgencyAnalytics API client wrapper
└── tests/
    ├── __init__.py
    ├── conftest.py                 # Shared pytest fixtures
    ├── test_config.py              # Configuration tests
    ├── test_client.py              # API client tests
    └── test_server.py              # MCP tool tests

关键设计决策

• 延迟客户端初始化 -API客户端在首次使用时创建并全局缓存，避免了启动时不必要的身份验证
• 同步HTTP -用途 httpx.Client （同步），因为AgentAnalytics API是一个没有并行优势的单一端点
• 错误字符串 -工具归还 "ERROR: ..." 字符串，而不是引发异常，遵循MCP约定进行优雅的错误处理
• JSON响应 -所有工具响应均使用 json.dumps(data, indent=2, default=str) 以获得一致、可读的输出

环境变量

测试

运行测试

# Install dev dependencies
uv pip install -e ".[dev]"

# Run all tests
uv run pytest

# Run with verbose output
uv run pytest -v

# Run a specific test file
uv run pytest tests/test_client.py

# Run a specific test class
uv run pytest tests/test_server.py::TestListCampaigns

测试结构

tests/
├── conftest.py         # Fixtures: sample_config, sample_campaign, sample_user,
│                       #   sample_backlink, sample_keyword_ranking, sample_api_response
├── test_config.py      # Tests for environment loading and validation (5 tests)
├── test_client.py      # Tests for auth headers, payload building, HTTP requests,
│                       #   and client methods (15 tests)
└── test_server.py      # Tests for each MCP tool with mocked client (14 tests)

所有测试均使用 unittest.mock 以模拟API客户端。在测试过程中没有进行真正的API调用。

故障排除

“缺少所需的环境变量：AGENCYANALYTICS_API_KEY”

确保您的 .env 文件存在于项目根目录中，并且包含您的API密钥：

AGENCYANALYTICS_API_KEY=your_api_key_here

“身份验证失败。请检查您的API密钥。”

1. 验证API密钥是否正确（管理设置>公司详细信息）
2. 确认您的帐户在具有API访问权限的卓越理财计划中
3. 确保您是管理员用户

“API错误”响应

AgentyAnalytics API可能会返回以下错误：

• 无效的资产名称或操作
• 创建/更新操作中缺少必填字段
• 无效的筛选值（例如，不存在的活动ID）
• 利率限制（具体限额未公开披露）

MCP服务器未出现在您的客户端中

1. 确保客户端的配置文件路径正确（请参阅客户端配置部分）
2. 验证配置中的Python路径是否指向 .venv 目录
3. 完全退出并重新启动客户端应用程序
4. 检查客户日志中的错误消息
5. 手动测试服务器：
   复制

   cd /path/to/mcp-agencyanalytics-python
   .venv/bin/python -m agencyanalytics_mcp.server
   

   服务器应无错误启动（它将等待stdin上的输入）

返回空结果的关键字

关键字一次只能查询一个活动。您必须提供 campaign_id:

list_keywords(campaign_id=123)

贡献

欢迎投稿！请随时提交拉取请求。

1. 分叉存储库
2. 创建功能分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add some amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

• 代理分析 API
• 模型上下文协议 对于MCP规范
• Anthropic Claude和MCP Python SDK
• 背后的团队 光标, 帆板运动, 克莱恩, 继续，以及 泽德 用于MCP支持

关于奥舍数码

该项目由以下人员维护 奥舍尔数字，澳大利亚的专业人工智能顾问。我们帮助企业整合人工智能解决方案，以简化运营并推动增长。

需要人工智能集成方面的帮助吗？ 联系

免责声明

这是一个非官方的、由社区维护的项目。它不隶属于AgencyAnalytics，也不由AgencyAnalytics官方维护或认可。