Notra

Notra MCP 服务

一个适用于 Notra API 的 MCP（模型上下文协议）服务。它用于管理帖子、品牌身份、集成、日程安排、GEO 可见性扫描、竞争对手、内容简报和 AI 流量分析。

设置

你可以在 Notra 工作区控制面板的 Developer > API Keys 中生成 API 密钥。

需要 Node.js 20 或更高版本。

Claude Desktop

添加到 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "notra": {
      "command": "npx",
      "args": ["-y", "@usenotra/mcp"],
      "env": {
        "NOTRA_API_KEY": "your-api-key"
      }
    }
  }
}

Claude Code

claude mcp add notra -- npx -y @usenotra/mcp

然后在启动 Claude Code 前，在 shell 中设置 NOTRA_API_KEY 环境变量。

Codex

export NOTRA_API_KEY=your-api-key
codex mcp add notra --env NOTRA_API_KEY="$NOTRA_API_KEY" -- npx -y @usenotra/mcp

运行 codex mcp list 验证连接。Codex 命令行、桌面应用和 IDE 扩展共用此 MCP 配置。

OpenCode

在 shell 中设置 NOTRA_API_KEY，然后将服务添加到项目级 opencode.json 或全局 ~/.config/opencode/opencode.json：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "notra": {
      "type": "local",
      "command": ["npx", "-y", "@usenotra/mcp"],
      "enabled": true,
      "environment": {
        "NOTRA_API_KEY": "{env:NOTRA_API_KEY}"
      }
    }
  }
}

Amp

运行 amp config edit 并将以下内容添加到设置中，或者将其放入 .amp/settings.json，以进行特定于工作区的配置：

{
  "amp.mcpServers": {
    "notra": {
      "command": "npx",
      "args": ["-y", "@usenotra/mcp"],
      "env": {
        "NOTRA_API_KEY": "${NOTRA_API_KEY}"
      }
    }
  }
}

在启动 Amp 前，在环境中设置 NOTRA_API_KEY。工作区 MCP 服务可能需要通过 amp mcp approve notra 批准。

账户 API 密钥

账户 API 密钥属于你，而非某个工作区，因此在你所属的每个工作区中都可使用。如果你属于多个工作区，请通过 NOTRA_ORGANIZATION_ID 选择此服务要操作的工作区：

{
  "env": {
    "NOTRA_API_KEY": "your-account-api-key",
    "NOTRA_ORGANIZATION_ID": "your-workspace-id"
  }
}

如果不设置，工具将失败，并提示你选择工作区。list_workspaces 无需选择工作区即可使用，并会显示各工作区的 ID。组织 API 密钥会忽略 NOTRA_ORGANIZATION_ID。

远程 MCP（OAuth）

托管的可流式 HTTP 服务 https://mcp.usenotra.com/mcp 以 OAuth 作为主要身份验证方式。它支持当前的 2026-07-28 MCP 协议以及旧版 2025 客户端。MCP 客户端应在以下位置发现受保护资源元数据：

https://mcp.usenotra.com/.well-known/oauth-protected-resource

该元数据指向 Notra 授权服务（WorkOS AuthKit）https://oauth.usenotra.com，此服务支持动态客户端注册（RFC 7591）。MCP 服务也会在 https://mcp.usenotra.com/.well-known/oauth-authorization-server 镜像授权服务器元数据。

工作区范围 URL

在 URL 中添加工作区 ID 或 slug，可将连接固定到一个工作区：https://mcp.usenotra.com/mcp/<workspace>。对于只接受 URL、无法发送自定义标头的客户端，这是选择工作区的方式。

• Claude：Settings > Connectors > Add custom connector，URL https://mcp.usenotra.com/mcp/acme

• Claude Code：claude mcp add --transport http notra https://mcp.usenotra.com/mcp/acme

• Cursor（~/.cursor/mcp.json）：

  {
    "mcpServers": {
      "notra": { "url": "https://mcp.usenotra.com/mcp/acme" }
    }
  }
  

使用范围受限的 URL 时：

• API 密钥将在该工作区中生效。URL 优先于 X-Notra-Organization-Id 标头。组织密钥只能用于其所属工作区的 URL；Notra API 会以 HTTP 403 拒绝其他工作区。
• OAuth 的工作方式与 /mcp 相同，但你授权的工作区必须与 URL 中的工作区一致。否则，请求会被以 HTTP 403 拒绝，而不会悄悄在另一个工作区中操作。OAuth 挑战会公布与 /mcp 相同的资源，因此客户端会获取普通的 Notra 令牌；URL 中的工作区由你授权的工作区强制限定。
• list_workspaces 不可用，因为此连接无法切换工作区。whoami 仍会显示当前工作区。
• 旧版 2025 会话属于其创建时使用的 URL；在其他 URL 上使用该会话 ID 会返回 HTTP 401。

API 密钥替代方案

远程连接也接受 Notra API 密钥作为静态 Authorization: Bearer … 标头。请在 Notra 工作区控制面板的 Developer > API Keys 下生成密钥。支持 OAuth 的客户端应优先使用 OAuth 流程，而不是手动配置密钥。

如果使用可以访问多个工作区的账户 API 密钥，请使用工作区范围的 URL，或添加 X-Notra-Organization-Id: <workspace-id-or-slug> 标头（X-Organization-Id 也可用）。服务会在每次调用时将其转发给 Notra API。旧版 2025 会话会绑定到初始化时使用的工作区；如果该会话中的请求指定了其他工作区，将被拒绝并返回 HTTP 401，因此请开启新会话以切换工作区。OAuth 连接会忽略该标头，因为每个令牌都绑定到用户授权时选择的工作区。

对于可自托管的 HTTP 部署，可通过以下配置进行 OAuth 验证：

WORKOS_AUTHKIT_DOMAIN=oauth.usenotra.com
WORKOS_CLIENT_ID=client_xxx
NOTRA_MCP_RESOURCE=https://mcp.usenotra.com

签发者为 https://{WORKOS_AUTHKIT_DOMAIN}，且必须与 AuthKit 签发的令牌中的 iss 声明匹配；不匹配时，所有承载令牌都会被拒绝。令牌签名会根据 https://{WORKOS_AUTHKIT_DOMAIN}/oauth2/jwks 进行验证。

当 NODE_ENV=development 时，默认的 AuthKit 域名为 essential-berry-67-development-2.authkit.app；生产环境默认使用 oauth.usenotra.com。auth.usenotra.com 是 WorkOS Authentication API 域名，不提供任何 OAuth 端点，因此在此处无法使用。

旧版 2025 会话在闲置 30 分钟后过期。每个 OAuth 用户或 API 密钥最多可持有 NOTRA_MCP_MAX_SESSIONS_PER_PRINCIPAL 个会话（默认值为 50）；超过上限时，会关闭其自身最近最少使用的会话。当服务持有的会话达到 NOTRA_MCP_MAX_SESSIONS 上限（默认值为 1000）时，新会话会被拒绝并返回 HTTP 503 和 Retry-After，而不会关闭其他用户的会话。

托管使用统计

HTTP 服务仅在 PostHog 中跟踪使用情况；每次分发工具调用时都会发送一个 mcp_tool_called 事件，包括未通过工具输入／输出验证的调用，或返回 isError: true 且 HTTP 状态码为 200 的调用。初始化、发现、健康检查以及在工具分发前被拒绝的请求不会计入统计。本地 stdio 服务不会发送使用事件，也不会联系 PostHog。

在托管部署中设置 PostHog 项目令牌即可启用跟踪：

POSTHOG_PROJECT_TOKEN=your-project-token

POSTHOG_HOST 默认值为 https://us.i.posthog.com；如果使用欧盟项目，请将其设为 https://eu.i.posthog.com。未设置项目令牌时，跟踪处于禁用状态。没有其他数据收集器，也没有 JSON 使用日志回退方案。

事件包含 tool_name、outcome（success、error 或 cancelled）、duration_ms、server_version、protocol_version、client_name、client_version 和 auth_kind。OAuth 事件还包含已验证的 WorkOS organization_id 和 user_id；API 密钥调用没有用户／工作区归属信息，且共用 PostHog distinct ID mcp:api-key，不得将其计为唯一用户。客户端身份由客户端自行报告，并归入已知客户端名称；未知名称会记录为 other。版本仅以数字 major.minor.patch 格式保留。未知工具名称会记录为 unknown。

使用事件中绝不会包含参数、结果、提示词、错误消息、标头、IP 地址、令牌、API 密钥和令牌哈希。事件以异步方式尽力投递，超时时间为 5 秒，每个进程最多允许 64 个待处理的 PostHog 请求。投递失败或丢弃时会发出不含凭据的警告，但不会导致工具调用失败。事件不会抽样，但 PostHog 投递记录不能用作审计或计费台账。

在 PostHog 中，按 mcp_tool_called 筛选，并按 tool_name、client_name 或 outcome 拆分。仅对 OAuth 调用统计不同的 organization_id／user_id 数量，并使用 duration_ms 计算延迟百分位数。

工具集

默认情况下会公开全部 96 个工具，这大约会占用 20k 个 Agent 上下文令牌。如需仅加载所需工具集，请使用 NOTRA_MCP_TOOLSETS（stdio 和 HTTP），或在远程端点上使用 toolsets 查询参数：

工具集	工具
content	帖子、品牌标识、集成、日程安排、事件触发器、技能、反馈收件箱
geo	项目和所有 GEO 工具

工作区工具和 submit_feedback 始终可用。

NOTRA_MCP_TOOLSETS=content npx -y @usenotra/mcp

https://mcp.usenotra.com/mcp?toolsets=geo

工具

工作区

工具	描述
whoami	显示当前工作区和经过身份验证的账户信息
list_workspaces	列出经过身份验证的账户可访问的已接受和待处理工作区

每个 MCP 连接都在与其 bearer token 绑定的工作区中运行；对于账户 API 密钥，则在通过 NOTRA_ORGANIZATION_ID 或 X-Notra-Organization-Id 标头选择的工作区中运行。如需在其他工作区中执行操作，请为该工作区授权或配置单独的连接；list_workspaces 可发现可访问的工作区，但不会切换工作区。

帖子

工具	描述
list_posts	列出帖子摘要，并可按排序、分页、状态、内容类型和品牌标识筛选
get_post	按 ID 获取单篇帖子
create_post	根据自定义标题和 Markdown 创建帖子
update_post	更新帖子的标题、Markdown 或状态
delete_post	删除帖子
generate_post	根据 GitHub 活动将帖子生成任务加入异步队列
get_post_generation_status	检查帖子生成任务的状态
get_post_schedule	获取帖子的发布日程和各发布目标的状态
schedule_post	安排现有帖子在 Notra 上发布，并可选择同时发布到 GitHub、X 或 LinkedIn
cancel_post_schedule	取消待发布的目标；已开始发布的目标会自行完成

帖子发布日程与下文的内容生成日程相互独立。schedule_post 需要 ISO 8601 格式的 scheduledAt 时间戳，可选接受 IANA timeZone（默认为 UTC），并且最多支持两个外部发布目标。GitHub 发布目标使用 list_integrations 返回的 repositoryId，并可选设置 merge 标志（默认为 true）；社交媒体发布目标使用已连接的 X 或 LinkedIn accountId。省略发布目标时，仅安排在 Notra 上发布。

品牌标识

工具	描述
list_brand_identities	列出所有品牌标识
get_brand_identity	按 ID 获取单个品牌标识
update_brand_identity	更新品牌标识设置
delete_brand_identity	删除品牌标识
list_brand_colors	列出品牌标识的品牌指南颜色
create_brand_color	添加品牌颜色
update_brand_color	更新品牌颜色
delete_brand_color	删除品牌颜色
generate_brand_identity	根据网站 URL 将品牌标识生成任务加入异步队列
get_brand_identity_generation_status	检查品牌标识生成任务的状态

集成

工具	描述
list_integrations	列出已启用的 GitHub 和 Linear 集成
create_github_integration	连接公开的 GitHub 仓库
delete_integration	删除 GitHub 或 Linear 集成

日程安排

工具	描述
list_schedules	列出已安排的内容生成任务
create_schedule	创建已安排的内容生成任务
update_schedule	更新已安排的内容生成任务
delete_schedule	删除已安排的内容生成任务

事件触发器

工具	描述
list_event_triggers	列出根据 GitHub 发布或推送生成内容的触发器
get_event_trigger	按 ID 获取单个事件触发器
create_event_trigger	创建事件触发器
update_event_trigger	替换事件触发器的配置
delete_event_trigger	删除事件触发器

Webhook

工具	描述
list_webhook_endpoints	列出已订阅 Notra 事件的 HTTPS 端点
delete_webhook_endpoint	移除 Webhook 订阅并取消尚未发送的投递
list_webhook_deliveries	列出 Webhook 投递，可按状态筛选
get_webhook_delivery	获取投递的载荷和尝试历史记录
retry_webhook_delivery	重试失败的 Webhook 投递

技能

工具	描述
list_skills	列出可重复使用的写作技能
get_skill	按名称获取单个技能
create_skill	创建可重复使用的写作技能
update_skill	更新可重复使用的写作技能
delete_skill	删除可重复使用的写作技能

项目

GEO 功能按项目划分。大多数 GEO 工具都需要 projectId；请先调用 list_projects 查找该 ID。GEO 工具需要组织级 API 密钥和 GEO 套餐。

工具	描述
list_projects	列出组织的 GEO 项目
get_project	根据 ID 获取单个项目
create_project	创建项目，可选择关联品牌
update_project	重命名项目或重新关联其品牌身份
delete_project	删除项目及其所有 GEO 数据（级联删除）

GEO 设置

工具	描述
get_geo_settings	获取受跟踪的公司、别名、语言、引擎和扫描配置
list_geo_engines	列出项目可跟踪的引擎 ID
update_geo_settings	替换设置文档并重新启动扫描周期

GEO 提示词和序列

工具	描述
list_geo_prompts	列出受跟踪的提示词（自定义和自动派生）
create_geo_prompt	跟踪新的提示词
update_geo_prompt	启用或停用受跟踪的提示词
delete_geo_prompt	停止跟踪提示词
import_geo_prompts	从行或 CSV 批量导入提示词
list_geo_sequences	列出多轮提示词序列
create_geo_sequence	创建提示词序列
update_geo_sequence	更新序列名称、步骤或启用状态
delete_geo_sequence	删除序列
run_geo_sequence	立即同步运行序列（会消耗 AI 积分，可能需要几分钟）

GEO 竞争对手

工具	描述
list_geo_competitors	列出受跟踪的竞争对手
upsert_geo_competitor	创建、更新或重命名竞争对手
suggest_geo_competitors	AI 根据域名发现可能的竞争对手
delete_geo_competitor	停止跟踪竞争对手
import_geo_competitors	从行或 CSV 批量导入竞争对手

GEO 扫描和可见度

工具	描述
create_geo_scan	触发异步可见度扫描（使用 AI 积分）
list_geo_scans	分页列出扫描
get_geo_scan	获取扫描及其状态
get_geo_snapshot	跨信号诊断摘要和建议的后续操作
get_geo_changes	两次最新扫描之间的变化
get_geo_visibility_overview	各答案引擎的提及率
get_geo_visibility_timeseries	各引擎每日提及次数
list_geo_prompt_result_summaries	筛选并分页列出结果，不包含完整答案或 URL
get_geo_prompt_result_detail	获取某次检查的完整答案和来源
get_geo_prompt_history	获取某个提示词的历史检查摘要
get_geo_sentiment	情感指标及与上一时期的比较
get_geo_sentiment_analysis	已存储的主题情感分析
list_geo_sentiment_evidence	分页列出情感指标背后的答案
list_geo_shelf_sources	分页列出引用来源库及机会状态
get_geo_competitor_share	按声量份额排列的头部品牌，可筛选品牌并设置数量上限
get_geo_language_share	各受跟踪语言的提及率
get_geo_competitor_detail	某个竞争对手的提及历史及相关提示词

GEO 内容简报

工具	描述
list_geo_content_gaps	竞争对手被提及而该品牌未被提及的提示词
list_geo_content_briefs	列出内容简报及其状态
plan_geo_content_brief	研究主题并规划简报（计费，可能需要几分钟）
get_geo_content_brief	获取包含完整文档和撰稿人状态的简报
update_geo_content_brief	编辑草稿简报的大纲和规划字段
approve_geo_content_brief	批准简报并启动文章撰写工具

Agent 就绪情况

工具	描述
get_geo_agent_readiness	最新就绪情况报告、评分历史以及正在进行的扫描（如有）
start_geo_agent_readiness_scan	将项目网站的就绪情况扫描加入队列

AI 流量

工具	描述
get_geo_traffic_overview	爬虫和 AI 引荐流量总量、来源及每日时间序列
get_geo_traffic_log	最近的单条 AI 爬虫／引荐请求
list_geo_traffic_journeys	按旅程分组的会话
get_geo_traffic_journey	某个旅程中的所有事件
list_geo_traffic_pages	AI 流量访问量最高的页面
get_geo_ingest_setup	跟踪安装代码片段和数据接入端点

反馈

工具	描述
submit_feedback	向 Notra 收件箱发送错误报告、功能请求、问题或赞扬（无需身份验证）
list_feedback	按状态、类型或项目列出组织收到的反馈
get_feedback	获取一条反馈及其 Agent 元数据
update_feedback	设置一条反馈的分诊状态

审查与数据边界

所有支持的操作都会通过 tools/list 预先列出。不提供通用 Agent 执行和审批工具，因为这些工具可能会运行动态发现的第三方操作。聊天记录和 Agent 会话可通过仪表板和 API 访问。请使用 Notra 仪表板管理 Agent 对话、私有仓库身份验证、Webhook 签名密钥和流量跟踪凭据。

工具输入用于特定任务的业务内容。请勿发送健康记录、生物识别数据、政府签发的身份标识、支付卡信息、凭据或无关的对话记录。请通过 OAuth 或本地配置进行身份验证，切勿通过工具参数进行身份验证。反馈仅接受用户批准的消息、可选标题和反馈类型。

开发

使用 Node 22.12+（Node 22）或 Node 24，以及 package.json 中固定的 pnpm 版本：

corepack enable
pnpm install --frozen-lockfile
pnpm test
pnpm run test:coverage
pnpm run typecheck
pnpm run format:check

src/schemas/api-responses.ts 中的工具输出架构由 Notra OpenAPI 规范生成。API 变更后运行 pnpm run generate:output-schemas；如果文件不是最新版本，CI 将失败。

Vitest 会直接针对源代码运行，并启用 Zod 编译。CI 会在针对 main 的拉取请求和推送时运行测试、类型检查、格式检查和构建。