内容
# Cituna MCP 服务器
[](https://www.npmjs.com/package/cituna-mcp)
[](./LICENSE)
将 **Cituna** 引入 Claude（桌面版、代码版或任何 MCP 客户端）。该服务器是 Cituna 后端的一个薄桥梁：它以您的身份进行身份验证，并调用应用程序使用的相同端点，因此 Google 的 OAuth 刷新令牌和您的数据库保留在服务器端，MCP 中不存储任何敏感信息。
它直接向 Claude 公开三个功能：
- **每日可见性跟踪** — 核心交付成果。您的跟踪提示每天在所有六个引擎（ChatGPT、Perplexity、Gemini、Claude、Grok、Google AI Overviews）中重新提问；`get_visibility` 返回最新的提示×引擎网格（是否引用？哪个位置？哪个模式？）以及您的当前分数，`get_engine_answers` 返回收据 — 每个引擎实际说的内容，它引用的品牌和来源 URL。
- **AI 可见性审计** — 每个引擎在所有六个引擎上的引用分数，查询×引擎引用矩阵，竞争对手引用，以及您可以从聊天中更新的优先级差距/行动队列。
- **实时 Google 搜索控制台** — 点击量/印象量/CTR/位置，热门查询和页面，以及任意搜索分析查询。
```
Claude ⇄ (stdio, MCP) ⇄ 此服务器 ⇄ (HTTPS + 您的密钥) ⇄ Cituna 后端 ⇄ AI 引擎 + Google 搜索控制台
```
## 工具
从 **Starter** 读取工具；**编写** 工具 — 两个标记为 **✍︎ Pro** — 需要 **Pro** 或更高版本（参见 [计划](#计划)）。7 天免费试用仅限应用程序，不提供 MCP 访问权限。
| 工具 | 计划 | 功能 |
|---|---|---|
| `whoami` | Starter+ | 身份验证账户（邮箱，工作区，角色），后端 URL，以及可用时您的计划（Starter/Pro/Max）和使用情况。调用此命令以确认连接。 |
| `list_audits` | Starter+ | 最近的 AI 可见性审计，按最新时间排序：扫描 ID，域名，日期，AI 引用分数，SEO/GEO/权威分数，开口数量。可选 `域名` 过滤。 |
| `get_audit` | Starter+ | 通过 `scanId` 详细查看一次审计：整体和每个引擎的分数，查询×引擎引用矩阵，竞争对手引用，顶部开口，以及通过/警告/失败的检查计数。 |
| `get_visibility` | Starter+ | **每日跟踪.** 指定 `品牌`（ID 或域名）的最新提示×引擎网格：每个跟踪提示和引擎 — 是否引用？位置，模式（实时/值/精简/关闭），状态 — 以及当前可见性分数和测量日期。 |
| `get_engine_answers` | Starter+ | **收据.** 对于 `品牌` + `提示`（可选 `引擎`）：每个引擎在最近一天给出的实际答案文本，它引用的品牌，来源 URL，以及您的引用位置。答案文本上限约 4k 字符，带有 `truncated` 标志。 |
| `list_gaps` | Starter+ | 指定 `域名`（或 `scanId`）的修复队列：每个开口的 `gapKey`，状态（待处理/进行中/已完成），标题，类别，影响，努力和具体修复。 |
| `set_gap_status` | **✍︎ Pro** | 使用 `list_gaps` 中的 `gapKey` + `域名` 更新一个开口的状态（待处理 / 进行中 / 已完成）。 |
| `run_scan` | **✍︎ Pro** | 为 URL 运行一个新的审计并返回完成的结果。耗时约 1 分钟，**消耗您每月配额的一个扫描**。 |
| `gsc_status` | Starter+ | 您的 workspace 是否已连接 GSC，连接的 Google 邮箱，以及已验证的 GSC 属性。 |
| `list_brands` | Starter+ | 您的 workspace 中跟踪的域名 — 方便的审计和 `gsc_*` 工具的输入。 |
| `gsc_overview` | Starter+ | 指定域名在过去 *N* 天的 GSC 摘要：总数（点击量/印象量/CTR/位置），热门查询和页面，国家/设备拆分，以及每日系列。 |
| `gsc_query` | Starter+ | **灵活的查询.** 任意搜索分析查询：任意维度，显式日期范围或尾随窗口，行限制和过滤器。 |
## 计划
MCP 服务器从 **Starter** 计划（**$39/mo**）及更高版本中包含（Starter / Pro / Max，映射到内部 `solo` / `agency` / `scale`）。**没有免费 MCP** — 7 天试用仅限应用程序，试用结束且无计划不能调用。
**读取/写入拆分.** 在 **Starter** 上，MCP 是 **只读** 的：您可以随意读取审计，开口，品牌和搜索控制台数据。**写入** 工具 — `run_scan`（消耗扫描）和 `set_gap_status`（修改您的操作队列） — 需要 **Pro** 或更高版本；在 Starter 上，您仍可以在应用程序中运行扫描和处理队列 **，而不能从 Claude 运行**。每个 MCP 调用也计入您的计划的每月 MCP 调用限额（Starter 5k / Pro 10k / Max 30k）。如果写入工具返回 *"…is a write action — it needs the Pro/Max plan"*，请在 <https://cituna.com/pricing> 升级。
## 安装
无需克隆，无需构建 — `npx` 获取：
```bash
npx -y cituna-mcp # （通常由您的 MCP 客户端启动，参见下文）
```
从源代码（用于开发）：
```bash
git clone https://github.com/Cituna/cituna-mcp && cd cituna-mcp
npm install && npm run build # → node dist/index.js
```
## 配置
设置 `CITUNA_API_URL`（后端基准 URL，默认为 `https://cituna.com`）和一个身份验证选项，按优先级顺序检查：
1. **个人 API 密钥 — 推荐.** 在应用程序中：**集成 → "Claude / MCP 访问" → 生成令牌**，复制 `cituna_sk_…` 值。长期有效，可在应用程序中撤销，不为您的密码。→ `CITUNA_API_KEY`
2. **会话 JWT.** 登录应用程序，开发者工具 → 应用程序 → Cookie，复制 `cituna_token`。有效期约 30 天。→ `CITUNA_TOKEN`
3. **邮箱 + 密码.** 服务器登录并在过期时自动刷新。→ `CITUNA_EMAIL` + `CITUNA_PASSWORD`
### Claude 代码
```bash
claude mcp add cituna --scope user \
--env CITUNA_API_KEY=cituna_sk_您的生成密钥 \
-- npx -y cituna-mcp
```
（后端 URL 默认值为 `https://cituna.com`；仅当指向不同的后端时添加 `--env CITUNA_API_URL=…`）
然后在 Claude 代码会话中：`/mcp` 确认已连接，并询问 *"what changed in my AI visibility this week?"*
### Claude 桌面版
编辑 `claude_desktop_config.json`（设置 → 开发者 → 编辑配置）：
```json
{
"mcpServers": {
"cituna": {
"command": "npx",
"args": ["-y", "cituna-mcp"],
"env": {
"CITUNA_API_KEY": "cituna_sk_您的生成密钥"
}
}
}
}
```
重启 Claude 桌面版。工具出现在 🔌 菜单下。
> 从源代码运行而不是 npm？使用 `"command": "node"`，`"args": ["/absolute/path/to/mcp/dist/index.js"]`。
## 内置提示（v1.5+）
服务器通过 MCP 提示 API 提供五个可重用的分析工作流程。在 Claude 中，它们出现在提示/命令选择器中；每个工作流程都运行一个编写好的配方，包括搜索控制台和引擎答案之间的连接，这是通用 SEO 工具无法实现的。
| 提示 | 参数 | 功能 |
|---|---|---|
| `why-am-i-not-cited` | `品牌`，`提示？` | 将每个未引用的提示分类为不可见 everywhere vs Google-visible-but-AI-invisible vs 部分引用，并提供实际引擎答案和 GSC 的证据 |
| `gsc-to-ai-gap` | `域名`，`天数？` | 具有真实 Google 印象的查询，其中 AI 从未引用您：排名的 AEO 目标列表 |
| `competitor-teardown` | `品牌`，`竞争对手？` | 从答案文本中计算引擎实际引用的内容，并与您配置的竞争对手列表进行差异比较 |
| `weekly-review` | `品牌` | 审计 + GSC + 差距队列的胜利，回归和本周的 3 个操作。仅读取 |
| `prioritize-fixes` | `域名` | 按 GSC 印象和未引用提示重新排序修复队列 |
所有五个默认均为只读；没有任何一个会触发付费扫描。
## 示例提示
- " **acme.com** 今天在 AI 搜索中的表现如何 — 哪些提示和引擎引用了我们？" (`get_visibility`)
- "对于 **acme.com**，在提示 *best CRM for dentists* 上，每个引擎实际说了什么以及引用了谁？" (`get_engine_answers`)
- "我的 AI 可见性本周发生了什么变化？" （使用 `list_audits` → `get_audit`）
- "**acme.com** 有哪些开放的修复机会？请将 schema 标记为完成。" (`list_gaps` → `set_gap_status`)
- "为 **acme.com** 运行一个新的可见性扫描并总结前 3 个修复机会。" (`run_scan`)
- "哪些 AI 引擎引用我们，为哪些问题？" （来自 `get_audit` 的引用矩阵）
- "**example.com** 在过去 28 天的搜索表现如何？" (`gsc_overview`)
- "按 `国家` 和 `设备` 分解 **example.com** 的流量。" (`gsc_query`)
- "显示包含 'pricing' 的 **example.com** 查询 — 过滤 `query contains pricing`。" (`gsc_query`)
## 连接 Google 搜索控制台
`gsc_*` 工具需要一次性在 Cituna 应用程序中连接 **，此处不连接**。此服务器中没有 Google OAuth，设计如此：浏览器同意流程发生在应用程序中，生成的刷新令牌仅在服务器端存储。
1. 在应用程序中，打开 **集成** 并点击 **连接 Google 搜索控制台** （付费计划；试用不包括 GSC）。
2. Google 将要求授予 Cituna **只读** 搜索控制台访问权限（`webmasters.readonly`）。Cituna 永远不会获得对任何 Google 内容的写入权限。
3. 选择包含您的域名的 **已验证搜索控制台属性** 的 Google 账户。这是人们经常遗漏的步骤：如果您选择的账户从未验证域名，则所有内容都会连接正常，但每个查询结果仍为空，因为 Google 在该账户中没有任何显示内容。
4. 在此处运行 `gsc_status`。它列出连接的账户和每个属性都可以查询的属性。如果您的域名不在列表中，请在搜索控制台（验证属性）而非 Cituna 中修复。
在应用程序中断开连接（集成，断开连接）也会立即撤销此服务器的访问权限。
## 身份验证如何到达 Google
此服务器从不持有 Google 凭证。它将您的 Cituna 密钥/JWT 作为 `Bearer` 令牌发送到后端；后端查找您的工作区的存储 GSC 刷新令牌，生成一个短期 Google 访问令牌，并查询搜索控制台 API。 在应用程序中断开 GSC 连接会立即切断此服务器的连接。
## 故障排除
| 症状 | 修复 |
|---|---|
| `No API key configured` | 没有配置凭证。生成令牌（集成 → Claude / MCP 访问）并设置 `CITUNA_API_KEY`。 |
| `API key invalid or expired` | 密钥被撤销或 JWT 过期。 在应用程序中生成新密钥，或重新复制 `cituna_token`；邮箱/密码自动刷新。 |
| `…is a write action — it needs the Pro/Max plan` | 您在 Starter 或试用版上调用了写入工具（`run_scan` / `set_gap_status`），其中 MCP 是只读的。在应用程序中运行，或升级到 Pro，访问 <https://cituna.com/pricing>。 |
| `requires a paid plan (Starter/Pro/Max)` | 工具被高级权限限制，您的计划不符合条件。升级访问 <https://cituna.com/pricing>。 |
| `{ "configured": false, ... }` | GSC OAuth 环境变量未在后端设置，或者您未连接 GSC，或者没有属性与域名匹配。按照消息提示操作。 |
| `Scan quota reached` | 您已用完每月扫描（或匿名每日限制）。升级或等待重置。 |
| 工具未显示 | 运行 `npm run build`；确认到 `dist/index.js` 的绝对路径；检查客户端的 MCP 日志。 |
| `ECONNREFUSED` | 后端未运行 / 错误的 `CITUNA_API_URL`。 |
**需要 Node 18.17+。**
---
## 关于此仓库
公共 [Cituna/cituna-mcp](https://github.com/Cituna/cituna-mcp) 仓库是一个 **发布的镜像**，而非工作树：服务器在 Cituna 的私有多模块仓库中开发并发布在标签上，因此工具界面和引擎列表与 API 实际提供的内容保持一致。镜像仓库无法直接合并拉取请求，但问题会被阅读和处理，因此请打开它们。
寻找 BI 仪表板而不是聊天客户端？Cituna 还提供 Looker Studio 连接器。参见 [cituna.com/integrations](https://cituna.com/integrations)。
MIT 许可。错误和请求：<https://github.com/Cituna/cituna-mcp/issues>
