Fullmention - Track how AI recommends your brand

@fullmention/mcp-server

FullMention MCP Server 提供安全、高性能的网关，让大模型（LLM）和 AI Agent（例如 Claude Desktop、Cursor 或自定义 Agent 网络）能够直接与 FullMention Public API 交互。

通过将 FullMention 的无状态模拟运行公开为原生 MCP 工具和结构化资源，您的 AI 模型可以无缝触发批量分析运行、跟踪进度、获取结果并分析可见度指标。

---

说明

📊 明确的排名系统

FullMention 中的 AI 推荐结果使用扁平排名列表（brandRankings、websiteRankings、productRankings）。

• 位置顺序： 这些列表中的每个项目都包含一个从 1 开始的 position 属性。位置 1 表示大模型上下文中的首选推荐／最显著建议，其后依次为排名较低的项目。
• 规则： 这些列表中的元素严格按照相关性和可见度显著程度排序。请勿按字母顺序对这些数组排序，否则会丢失宝贵的可见度信息！

---

快速开始：连接您的 AI 客户端（本地桌面端）

要将 FullMention MCP Server 连接到本地编辑器或聊天客户端，请使用以下配置设置客户端。

1. Claude Desktop 设置

将以下配置添加到 claude_desktop_config.json（在 macOS 上通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json，在 Windows 上通常位于 %APPDATA%\Claude\claude_desktop_config.json）：

{
  "mcpServers": {
    "fullmention": {
      "command": "npx",
      "args": ["-y", "@fullmention/mcp-server"],
      "env": {
        "FULLMENTION_API_KEY": "your_fm_live_key_here"
      }
    }
  }
}

提示

固定版本： 为避免破坏性变更影响生产工作流，使用 npx 启动时，可考虑固定到特定的 SemVer 版本： "args": ["-y", "@fullmention/[email protected]"]

2. Cursor 设置

1. 打开 Cursor 设置，然后前往 Features -> MCP。
2. 点击 + Add New MCP Server。
3. 填写配置：
   • Name： FullMention
   • Type： stdio
   • Command： npx -y @fullmention/mcp-server
4. 将环境变量 FULLMENTION_API_KEY 设置为您的 API 密钥。
5. 点击 Save。

---

核心架构与智能防护

FullMention MCP Server 从设计之初就具备 AI 安全性和高资源效率，可自动保护您的 API 配额和额度预算：

• 🛡️ 内存查询防护： 缓存查询响应（TTL 为 60 秒），防止冗余的 Agent 循环耗尽外部 API 速率限制。
• 🚦 状态轮询护栏： 检测对正在运行的批次状态进行的快速连续轮询。如果 AI Agent 在 8 秒内再次轮询服务，服务会拦截网络调用，并返回带有 [POLLED_TOO_FAST_CACHED_WARNING] 的缓存状态，从而节省网络开销并减轻 API 压力。
• 📊 服务端声量占比： 使用 get_share_of_voice 在服务端自动计算品牌可见度，彻底避免大模型产生数学幻觉。
• 🚀 服务端 Token 优化： 支持 format: "markdown" 参数。MCP 服务不会向大模型发送冗长的原始 JSON，而是自动将数据整理为高度压缩、信息密集的 Markdown 表格，大幅节省 Token 开销并显著降低大模型输入成本。

---

通过云端部署扩展（SSE 模式）

对于 SaaS 和云架构，FullMention MCP Server 开箱即支持 SSE（Server-Sent Events）HTTP 传输，并可动态运行。

以 SSE 模式启动：

要在端口 3000（或配置的 PORT / FULLMENTION_MCP_PORT）上启动 HTTP 网关：

npx -y @fullmention/mcp-server --sse

100% 安全的指标端点

以 SSE 模式托管时，您可以通过以下端点查看诊断信息和实时缓存性能指标：

curl http://localhost:3000/diagnostics

---

工具与参数详细参考

FullMention MCP 服务提供 7 个专用工具。以下是每个工具的完整参数架构和响应格式：

📊 系统与配额工具

1. get_status

从 FullMention 平台获取动态系统和引擎状态。

• **参数：**无。
• 响应（JSON）：

  {
    "status": "operational",
    "engines": {
      "openai": "operational",
      "openaiMini": "operational",
      "gemini": "operational"
    }
  }
  

2. get_quota

获取账户配额限制和当前用量。

• 参数：
  • bypassCache （boolean，可选）：设为 true 时绕过缓存。
• 响应（JSON）：

  {
    "limit": 10000,
    "used": 2350,
    "extra": 0,
    "remaining": 7650
  }
  

3. get_usage_stats

获取详细的配额和额度统计信息，并显示预算警告。

• 参数：
  • bypassCache （boolean，可选）：设为 true 时绕过缓存。
• **响应：**关于剩余额度、每月上限和当前额度定价矩阵的 Markdown 摘要。

---

🚦 模拟与运行

4. trigger_run

触发异步、无状态的模拟运行。

• 参数：
  • keywords （字符串数组，必需）：要模拟的关键词列表（最多 500 个）。
  • engines （字符串数组，必需）：要使用的 AI 搜索引擎（例如 ["openai", "openai-mini", "gemini"]）。
  • country （字符串，必需）：国家/地区上下文（例如 "Denmark" 或 "United States"）。
  • language （字符串，必需）：语言上下文（例如 "Danish" 或 "English"）。
  • location （字符串，可选，可为 null）：可选的具体城市上下文（例如 "Copenhagen"）。
  • fanout （boolean，可选）：启用网络搜索扩展（每个关键词额外消耗 1 个额度）。
  • webhookUrl （字符串，可选，可为 null）：运行完成时用于回调的可选完整 HTTP/S URL。
  • idempotencyKey （字符串，可选）：用于防止重复运行的唯一字符串。
• 响应（JSON）：

  {
    "id": "run_987abc",
    "status": "queued",
    "progress": {
      "status": "queued",
      "totalRequests": 10,
      "completedRequests": 0,
      "failedRequests": 0,
      "percentage": 0
    },
    "estimatedCredits": 10,
    "createdAt": "2026-06-10T22:00:00.000Z",
    "completedAt": null,
    "expiresAt": "2026-06-11T22:00:00.000Z",
    "statusUrl": "https://api.fullmention.com/v1/runs/run_987abc"
  }
  

5. get_run_status

使用 runId 获取运行详情、进度和结果。

• 参数：
  • runId （字符串，必需）：运行的 ID。
  • format （"compact" | "raw" | "markdown"，可选，默认值："compact"）：响应格式。
  • bypassCache （boolean，可选）：设为 true 时绕过缓存。
• **响应：**内容精简的 Markdown 表格（当 format: "markdown" 时），或运行及其结果的精简 JSON 表示。

6. get_fanout_sources

获取特定推荐结果的完整分页网络来源和搜索查询。

• 参数：
  • runId （字符串，必需）：批次运行的 ID。
  • resultId （字符串，必需）：结果快照 ID。
  • limit （数字，可选）。
  • cursor （字符串，可选）。
• 响应（JSON）：

  {
    "data": [
      {
        "domain": "ahrefs.com",
        "url": "https://ahrefs.com/blog/best-seo-tools/",
        "title": "Best SEO Tools for 2026",
        "snippet": "Read our comprehensive review of top SEO suites...",
        "crawledAt": "2026-06-10T22:05:00.000Z"
      }
    ],
    "meta": {
      "nextCursor": "eyJza2lwIjoxfQ=="
    }
  }
  

7. get_share_of_voice

在服务端计算已完成运行的声量占比百分比和平均排名。

• 参数：
  • runId （字符串，必需）：要分析的已完成运行 ID。
  • brands （字符串数组，可选）：用于比较的指定目标品牌。
  • format （"json" | "markdown"，可选，默认值："markdown"）。
  • bypassCache （boolean，可选）。
• **响应：**Markdown 表格报告，或包含可见度百分比的汇总 JSON。

---

暴露的原生资源

AI 模型可以使用以下结构化原生资源直接查询数据：

• fullmention://schema/openapi — 机器可读的 API 契约。
• fullmention://runs/{runId} — 特定已完成运行的 Markdown 摘要报告。

---

AI 引导提示词

MCP 服务中包含预定义的 Agent 模板：

• brand-analysis：分析已完成运行的结果中竞争对手的出现情况。
• credit-optimization：根据关键词和引擎数量，为计划中的运行提供额度成本建议。
• gap-analysis：分析运行中竞争对手可见、而自有品牌缺失的关键词差距。
• citation-coverage：汇总运行中的域名和网络来源。
• category-dominance：根据运行中的 AI 推荐，展示类别主导情况。
• executive-digest：根据运行生成每周高管 KPI 摘要。