将 NoteLLM 连接到 AI 客户端 | NoteLLM

通过官方插件、skills 和托管 MCP server，把 NoteLLM 连接到 Codex、Claude Code 和 Claude

这是什么

NoteLLM 提供了托管 MCP server 和官方插件，让 AI agent 可以通过 skills 检索你保存的原始想法转录。

官方插件: hx23840/notellm-plugin
MCP Server URL: https://notellm.app/api/mcp
传输方式: Streamable HTTP
认证方式: OAuth 2.1 + PKCE
最小权限: asr:read

推荐优先安装官方插件。插件会为支持的本地客户端安装 NoteLLM skills，并配置托管 MCP server。

会安装什么

插件提供两个 skills：

Skill	作用
`notellm-recent-notes`	立即展示最近的 NoteLLM notes
`notellm-search-notes`	基于当前任务或对话上下文搜索 NoteLLM

MCP server 提供底层工具：

Tool	作用
`list_recent_notes`	获取最近的 NoteLLM notes
`search_notes`	按主题、短语、项目或人物搜索 notes
`get_note`	打开指定 note
`batch_get_notes`	批量获取少量已知相关 notes

这些 MCP tools 会在插件和 OAuth 配置完成后由 agent 调用。它们不是 skills，也不会出现在 skills 列表里。

支持矩阵

客户端	推荐配置方式	认证方式	当前说明
Codex	`npx notellm-plugin install --client codex`	客户端触发 OAuth	推荐用于 Codex CLI / IDE
Claude Code	`npx notellm-plugin install --client claude-code`	首次使用 MCP tool 时触发 OAuth	需要在你使用 Claude Code 的项目目录运行
Claude	自定义 connector	浏览器 OAuth	推荐用于网页 Claude
OpenClaw	暂缓	暂不支持	等待可靠的 device authorization flow 和 runtime adapter

Codex

安装官方插件：

npx notellm-plugin install --client codex

安装器会添加 NoteLLM skills，并注册 MCP server。

Codex 在添加 MCP server 时会启动 NoteLLM OAuth 流程。打开授权链接，登录 NoteLLM，并批准 asr:read 权限。

检查 MCP server：

codex mcp list

你应该能看到：

notellm  https://notellm.app/api/mcp

然后启动 Codex，直接请求：

Show my recent NoteLLM notes.

你也可以直接选择 skill。在 Codex 里，它们可能带有 package 前缀：

$notellm:notellm-recent-notes
$notellm:notellm-search-notes

Claude Code

在你使用 Claude Code 的项目目录运行安装器：

npx notellm-plugin install --client claude-code

Claude Code 的 MCP 配置是项目级的。安装完成后，输出里通常会出现类似内容：

Added HTTP MCP server notellm with URL: https://notellm.app/api/mcp to project config
File modified: .mcp.json

这是预期行为。Claude Code 不会在 mcp add 阶段立即启动 OAuth。

从同一个项目目录启动 Claude Code：

claude

从 skills 列表里选择 notellm-recent-notes，或者直接请求：

Show my recent NoteLLM notes.

Claude Code 会在客户端会话第一次使用 NoteLLM MCP tool 时启动 OAuth。

可用的检查命令：

claude mcp list

同时安装到两个本地客户端

如果要同时为 Codex 和 Claude Code 安装 NoteLLM：

npx notellm-plugin install --client all

也可以使用交互式安装器：

npx notellm-plugin install

更新和卸载使用同样的 client 选择方式：

npx notellm-plugin update --client codex
npx notellm-plugin uninstall --client codex

可以把 codex 替换成 claude-code 或 all。

Claude

适用于 Claude 网页版或支持自定义 connector 的 Claude 客户端。

打开 Claude 设置中的 Connectors
选择 Add custom connector
填入 https://notellm.app/api/mcp
保存后点击 Connect
按提示在浏览器中登录 notellm.app 并授权 asr:read

连接完成后，再在对话里告诉 Claude：

Use the NoteLLM MCP tools to list my recent raw notes with limit 10. Show them briefly first. If I mention a topic, search_notes for it. If I choose one note, open it with get_note.

怎么使用

直接用自然语言请求即可：

Show my recent NoteLLM notes.

Find my NoteLLM notes about the mobile app launch.

What did I previously say in NoteLLM about pricing?

选择 notellm-recent-notes 时，agent 应该立即读取最近 notes。

选择 notellm-search-notes 时，agent 应该基于当前对话搜索 NoteLLM。如果没有可用主题，它会先询问要搜索什么。

连接成功后的推荐用法

推荐按这个顺序调用：

先调用 list_recent_notes，limit 设为较小值，例如 10
先向用户简要展示最近记录
如果用户提到某个主题、项目或之前的想法，再调用 search_notes
用户选中具体一条或多条后，再调用 get_note 或 batch_get_notes

不要默认一次性读取大量原始转录内容。

手动配置时需要的信息

大多数用户应该使用插件安装器，而不是手动配置。如果你的客户端支持 MCP 自动发现，通常只填 server URL 即可。

MCP Server URL: https://notellm.app/api/mcp
OAuth Protected Resource Metadata: https://notellm.app/.well-known/oauth-protected-resource
OAuth Authorization Server Metadata: https://notellm.app/.well-known/oauth-authorization-server
OAuth Scope: asr:read

常见问题

为什么推荐插件，而不是只添加 MCP？

MCP server 负责让 agent 访问你的原始 NoteLLM 转录。skills 负责告诉 agent 什么时候使用这种访问能力，以及如何把检索范围控制得足够窄。

如果你希望行为更稳定，而不是每次都在 prompt 里解释怎么调用 NoteLLM，应该使用插件。

为什么不能直接把一段提示词发给 AI？

因为大多数 MCP 客户端都要求你先完成两件事：

在客户端里注册 MCP server
先完成 OAuth 认证

只有在连接和认证都完成后，AI 才能真正调用 NoteLLM 的 MCP 工具。

为什么工具名会被当普通文本？

如果客户端还没有成功加载 notellm 这个 MCP server，模型只会把 list_recent_notes 或 search_notes 当成普通字符串，而不是可调用工具。

如何判断是否已经连接成功？

以客户端自己的 MCP 状态页或命令输出为准：

Codex: codex mcp list
Claude Code: claude mcp list 或 /mcp
Claude: 设置里的 connector 状态