Flexnote MCP 服务：在 Cursor 与 Codex 中访问本地知识库

在 Cursor、Codex 等开发环境中工作时，通常仍需查阅本地笔记中的结论、文献摘录或白板结构。若依赖复制粘贴或切换至其他对话窗口，知识库与当前工作流会被拆成两套系统，上下文难以保持完整。

Flexnote 桌面端现已内置 MCP 服务（Model Context Protocol）。服务仅监听本机 127.0.0.1。已支持该协议的客户端（包括 Cursor、Claude Desktop、Codex）可直接检索、读取并写入当前笔记库。数据仍保存在用户设备上，不会上传至第三方笔记云。

一、与应用内 Flexnote AI 的区别

MCP 是一项开放协议，用于向外部人工智能客户端声明可调用的工具。客户端获取工具列表、按名称发起调用，并接收 JSON 文本结果。模型由客户端自行选择，Flexnote 不介入其计费与供应商。

应用内的 Flexnote AI 运行于侧栏对话：使用用户在设置中填写的 API Key，回答可附带引用，Agent 亦可编辑白板。MCP 则将同一知识库开放给外部开发工具，以便在编码或写作界面中直接操作日记、卡片、待办与白板，而无需离开当前窗口。

二、能力范围

可查询当前工作空间中的卡片、日记、白板、待办、标签与收藏。写入类工具需关闭「只读模式」。画布相关操作需提供白板 ID；若目标白板未打开，Flexnote 将先行跳转并等待画布就绪后再执行，以避免客户端请求超时。

三、启用方式

MCP 为专业版功能，须登录有效会员账号，且 Flexnote 桌面客户端处于运行状态。退出应用后，本机端口将关闭，外部客户端无法连接。

1. 打开 Flexnote → 设置 → MCP 服务。
2. 开启服务。服务仅绑定本机回环地址，默认端口为 39125。
3. 按客户端类型复制配置：Cursor / Claude Desktop 使用 HTTP JSON；仅支持 command 启动的客户端使用 stdio 桥；Codex CLI 使用 TOML。
4. 将配置写入对应客户端。访问令牌仅用于本机鉴权，请勿提交至公开代码仓库或对外传播。

建议同时确认以下选项：只读模式仅开放查询类工具，适用于接入验证；亦可按工具关闭不希望外部模型调用的写入能力。

四、接入 Cursor、Claude Desktop 与 Codex

Cursor / Claude Desktop

使用设置页提供的 HTTP 配置。核心字段为本机 URL 与 Bearer 令牌，示例如下：

{
  "mcpServers": {
    "flexnote": {
      "url": "http://127.0.0.1:39125/mcp",
      "headers": { "Authorization": "Bearer 你的令牌" }
    }
  }
}

Codex CLI

Codex CLI 通常通过 stdio 桥接：由 Node 运行 Flexnote 提供的脚本，将标准输入转发至本机 HTTP 端点。设置页可复制 TOML 配置并定位桥接脚本。请在环境变量中设置 FLEXNOTE_MCP_URL 与 FLEXNOTE_MCP_TOKEN。

五、调用示例

连接成功后，无需记忆工具名称，可直接使用自然语言。以下语句可用于验证接入是否正常：

• 「当前 Flexnote 工作空间是哪一个？列出最近的白板和五张卡片，不要修改任何数据。」
• 「将这段结论追加到今天的日记。若当天日记不存在则创建。请勿保存为普通笔记卡片。」
• 「新建一张笔记，标题为《MCP 试验》，正文须以 Markdown 一级标题开头。」
• 「在指定白板（提供 whiteboardId）上创建两张便签并建立连线，然后读取画布布局。」
• 「列出待办事项，并将其中一项标记为完成。」

写入成功后，Flexnote 将在窗口中显示提示。若存在对应实体，可选择「查看」打开相应页面；否则可选择刷新界面。提示默认保持显示，直至用户关闭。

六、安全说明

服务仅监听本机地址。同一设备上持有访问令牌的其他进程亦可调用上述工具，请将令牌按凭据管理。如需作废旧配置，可在设置中重新生成令牌，原配置立即失效。

一旦开放写入类工具，外部模型即可修改知识库。在验证阶段建议启用只读模式，或关闭创建、删除及白板相关工具。MCP 仅作用于当前打开的工作空间，操作前请确认空间选择无误。

七、适用范围

• 仅使用浏览器、不运行桌面客户端时，本机不存在 MCP 端口，无法接入。
• 本服务不是团队共享网关，也不提供公网访问，不适用于将笔记库开放给其他成员。
• Flexnote 不以实时多人白板为产品方向，MCP 亦不提供该项能力。完整产品定位见 Flexnote 是什么。

八、开始使用

请将桌面客户端更新至包含 MCP 的版本，使用专业版账号登录，在设置中启用服务，并将配置写入 Cursor 或 Codex。建议先以只读模式完成检索验证，再开放写入。客户端下载见 下载页；专业版说明见 定价。

若已在使用应用内知识库 Agent，无需调整既有笔记方法。MCP 仅将同一本地知识库接入外部开发工具。