Naumu

@naumu/mcp

用于 Naumu 的 MCP 服务——让您可以从 Claude Code、Cursor 和其他 AI Agent 访问知识图谱。

此仓库是已发布的 @naumu/mcp 包的公开主页：包含文档、问题和版本发布。开发工作在 Naumu 单体仓库中进行。发现 Bug 或希望添加工具？提交问题。

Naumu 通过两种传输方式支持 MCP：

1. 通过 OAuth 连接远程服务，地址为 https://naumu.ai/api/mcp——推荐方式。您通过浏览器登录，无需创建、粘贴或同步 API 密钥。此方式不涉及此软件包。
2. 本地 stdio，即此软件包，可按需使用 npx 启动，并通过 API 密钥进行身份验证。适用于不支持浏览器 OAuth 的客户端：CI 作业、机器人和外部 Agent 身份，以及仅支持 stdio 的旧版运行环境。

推荐设置：通过 OAuth 连接远程 MCP

只需注册一次服务。会话首次使用 Naumu 工具时，浏览器会打开，以便您登录并批准访问权限。之后，所有会话都可以使用这些工具。

Claude Code

claude mcp add --transport http --scope user naumu https://naumu.ai/api/mcp

--scope user 会将服务注册到整台机器，而非当前项目，因此无需在每个仓库中重复注册。

Cursor

{
  "mcpServers": {
    "naumu": {
      "url": "https://naumu.ai/api/mcp"
    }
  }
}

OAuth 客户端 ID 和密钥字段留空即可。Naumu 会在登录期间使用动态客户端注册（DCR）自动为您注册客户端。

其他支持 MCP 的客户端若支持远程服务，配置方式也相同：将其指向 https://naumu.ai/api/mcp，然后通过浏览器登录。请使用前端源站（naumu.ai），而不是后端地址——登录和授权需要使用您的 Naumu 会话，该会话位于前端源站。

您可以随时在 Naumu 的 Settings > Your agents 中，从 Active access 列表撤销已连接工具的访问权限。

完整操作指南请参阅 本地 MCP。

备用设置：使用 API 密钥的本地 stdio 服务

如果您的客户端不支持浏览器 OAuth，请使用此软件包——例如 CI、机器人和外部 Agent 身份，或仅支持 stdio 的运行环境。

1. 获取 API 密钥

1. 在 Naumu 中打开 Settings > Your agents。
2. 选择 Create an API key，并为密钥设置一个易于识别的名称（例如，使用它的工具名称）。
3. 立即复制密钥。密钥只会显示一次，之后无法找回。密钥以 nmu_ 开头。

每种工具使用单独的密钥，这样即使密钥泄漏，也只会影响该密钥。

2. 配置客户端

无需全局安装此软件包；客户端会按需使用 npx 启动它。

Claude Code

claude mcp add naumu -s user \
  -e NAUMU_API_KEY=nmu_your_key_here \
  -- npx -y -p @naumu/mcp naumu-mcp

Cursor

{
  "mcpServers": {
    "naumu": {
      "command": "npx",
      "args": ["-y", "-p", "@naumu/mcp", "naumu-mcp"],
      "env": {
        "NAUMU_API_KEY": "nmu_your_key_here"
      }
    }
  }
}

环境变量

变量	必需	默认值	说明
NAUMU_API_KEY	是	-	您的 API 密钥（以 nmu_ 开头）
NAUMU_API_URL	否	https://naumu.ai	Naumu API 基础 URL。无需设置此变量

可用工具

两种传输方式提供相同的工具集。标记为 bot 的工具仅会为机器人身份密钥（nmu_bot_*）注册；这类密钥还会根据身份权限获得经过筛选的工具子集。

空间和成员

工具	说明
naumu_list_graphs	列出密钥可访问的所有空间（图谱），包含 ID、名称和角色
naumu_create_graph	创建一个由已通过身份验证的用户拥有的空白空间
naumu_list_members	列出空间成员及其角色
naumu_whoami	返回调用密钥所属的身份（用户，或包含其图谱和允许使用的工具的机器人身份）

架构

工具	描述
naumu_get_schema	获取空间的架构（节点类型、属性、连接）
naumu_update_schema	用全新的定义替换架构
naumu_add_node_type	添加一种节点类型，无需重新提交整个架构
naumu_add_connection	添加一条从现有节点类型指向另一节点类型的连接
naumu_add_attribute	在现有节点类型上添加或扩展属性
naumu_list_schema_violations	根据架构审查空间并报告违规情况

读取图谱

工具	描述
naumu_search	对图谱节点进行混合搜索（语义加文本）
naumu_filter	按类型和属性筛选节点，结果完整且确定
naumu_get_node	获取单个节点及其属性、边、备注、讨论串和生成的上下文
naumu_list_node_connections	列出单个节点的连接
naumu_list_dense_nodes	按子节点数量查找连接过多的枢纽节点
naumu_ask	向 @Naumu 提问，获取基于节点综合生成的答案，并附上来源和置信度

写入图谱

工具	描述
naumu_add_node	一次调用创建 1-25 个节点
naumu_update_node	覆盖现有节点的属性
naumu_remove_node	删除节点及其所有连接（不可撤销）
naumu_add_edge	在现有节点之间创建 1-25 条边
naumu_remove_edge	删除由 (source, target, label) 标识的一条边
naumu_remove_edges_bulk	在一次原子调用中删除 1-100 条边
naumu_reparent	以原子方式替换节点的父级边
naumu_batch_reparent	将 1-25 个节点重新设为同一个新父节点的子节点
naumu_delegate	将任务交给 @Naumu 异步执行；返回一个用于轮询的 threadId

讨论串和主题

工具	描述
naumu_list_threads	按最近活动时间列出讨论串，并附带 isParticipant 标记
naumu_get_thread	获取单个讨论串及其人类和机器人参与者名单
naumu_read_thread	读取讨论串消息；每条消息都带有 processing 或 complete 状态
naumu_post_message	在你参与的讨论串中发布 Markdown 消息
naumu_create_thread	机器人 开始新的对话，添加参与者，发布首条消息，并可选择归入主题
naumu_add_reaction	为消息添加表情回应（幂等）
naumu_remove_reaction	移除你自己的消息回应
naumu_typing	显示或隐藏你在讨论串中的“正在输入”指示状态
naumu_list_topics	列出空间的主题（归档目的地），供 topicIds 使用
naumu_create_topic	创建主题；仅管理员可操作，名称必须是小写 slug

备注

工具	描述
naumu_create_note	创建备注，可在同一次调用中附带完整的 Markdown 正文
naumu_note_read	读取备注当前的 Markdown 内容及其关联的节点
naumu_note_append	在备注末尾追加 Markdown 内容块
naumu_note_insert	在指定标题后立即插入 Markdown 内容
naumu_note_replace_section	替换指定标题下的正文
naumu_note_delete_section	删除指定标题及其正文（不可撤销）
naumu_note_replace	替换整篇备注的内容（不可撤销）
naumu_note_find_replace	在备注中查找并替换字面文本

附件

工具	描述
naumu_request_attachment_upload	获取用于上传文件的预签名 S3 URL，然后通过 attachmentIds 引用该文件
naumu_get_attachment	通过 attachmentId 读取聊天附件
naumu_persist_canvas_attachment	将画布绑定的待处理附件提升为已持久化附件

空间准入

工具	描述
naumu_admission_status	显示哪些人可以自动加入空间，以及哪些人正在等待审批
naumu_whitelist_members	将邮箱列入白名单，使这些人在登录时自动加入
naumu_resolve_admission	加入（或申请加入）仓库的 .naumu 文件所引用的空间
naumu_resolve_join_request	批准或拒绝待处理的加入申请

ChatGPT 兼容性

OpenAI MCP 接口要求工具的名称必须是 search 和 fetch。它们会封装跨空间搜索和节点读取，并按照客户端期望的响应格式返回数据。

工具	描述
search	搜索所有可访问的空间；返回 { results: [{ id, title, url }] }
fetch	获取 search 返回的节点；返回 { id, title, text, url }

故障排除

当 stdio 服务配置错误时，它会在 MCP 握手前退出，而大多数客户端只会显示没有服务，且不提示错误。运行内置自检，查明原因：

npx -y -p @naumu/mcp naumu-mcp doctor

自检会依次检查是否已设置 NAUMU_API_KEY（绝不会打印密钥本身）、API 是否可访问并接受该密钥，以及此构建是否与最新发布版本一致。每项检查都会打印一行结果，并给出最终判定；若有任何检查失败，则以非零状态码退出：

naumu-mcp doctor (v0.11.1, API https://naumu.ai)

[fail] API key: NAUMU_API_KEY is missing from the environment
[warn] API: reachable (https://naumu.ai answered HTTP 403), but there is no NAUMU_API_KEY to verify
[ok]   Version: running 0.11.1 (npm latest)

Verdict: 1 check failed - the MCP server will not work until this is fixed.
Most likely fix: Set NAUMU_API_KEY - create a key at https://naumu.ai/settings (Settings > Your agents > Create an API key)

请使用与 MCP 客户端相同的环境运行自检，否则密钥检查会检查你的 shell 环境，而非客户端配置。

许可证

MIT