为 Claude Code 和 Codex 配置 PandaNpc MCP 服务器

更新于 2026-08-18

PandaNpc MCP 服务器将兼容 MCP 的编码代理连接到您的 PandaNote 知识库、工作日志、计划任务、模型配置和代理服务中心。当代理需要持久的项目上下文，而不是每次都从空对话开始时，它非常有用。

该服务器通过 MCP 的标准输入/输出传输在本地运行。当会话打开时，您的 MCP 客户端会启动 pandanpc-mcp 进程；您无需暴露端口或运行单独的 Web 服务器。

安装前

您需要：

Node.js 和 npm 在 MCP 客户端运行的同一环境中可用。
拥有一个可访问用于验证的电子邮件地址的 PandaNpc 账户。
Claude Code、OpenAI Codex、Cursor 或其他支持本地 stdio MCP 服务器的客户端。

如果您希望代理在您自己的某台电脑上安排工作，请先安装并连接先安装 PandaPaw。笔记和工作区工具不需要在线的 PandaPaw 设备。

安装或更新 MCP 服务器

在 macOS、Linux 或 Windows 上全局安装该软件包：

bash

npm install -g @pandanpc/mcp-server

确认该可执行文件在您的 shell 中可见：

bash

pandanpc-mcp --help

每当您想要更新时，运行相同的 npm 命令。更新后请重启 MCP 客户端，因为已在运行的客户端会保留其最初启动的进程版本。

当某个工具或其行为与旧截图或教程不同时，请查阅 MCP 服务器版本历史。

将 PandaNpc 添加到 Claude Code

最可靠的方法是使用 Claude Code 自带的配置命令。如果您希望 PandaNpc 在每个项目中都可用，请使用用户范围：

bash

claude mcp add --scope user pandanpc -- pandanpc-mcp

当配置应通过当前仓库共享时，请改用 --scope project；当配置应仅适用于当前项目中的您本人时，请使用 --scope local。

检查已注册的服务器：

bash

claude mcp get pandanpc
claude mcp list

您也可以手动在 Claude Code 安装所使用的 MCP 配置中配置 stdio 服务器：

json

{
  "mcpServers": {
    "pandanpc": {
      "command": "pandanpc-mcp"
    }
  }
}

将 PandaNpc 添加到 OpenAI Codex

Codex 可以通过命令行注册相同的本地进程：

bash

codex mcp add pandanpc -- pandanpc-mcp

验证已保存的配置：

bash

codex mcp get pandanpc
codex mcp list

~/.codex/config.toml 中对应的条目是：

toml

[mcp_servers.pandanpc]
command = "pandanpc-mcp"

添加服务器后，请重启 Codex 或打开新会话。如果您维护自定义的 Codex 配置文件，请将 MCP 表放在该文件中，而不是在多个文件中重复配置。

配置 Cursor 和其他 MCP 客户端

对于 Cursor，使用与 Claude Code 相同的 JSON 结构，将本地服务器添加到 ~/.cursor/mcp.json。对于 Windsurf 和其他客户端，创建一个 stdio MCP 服务器，其命令为 pandanpc-mcp，参数列表为空。

该可执行文件必须位于图形应用程序继承的 PATH 中。如果它在终端中可用，但桌面客户端报告“找不到命令”，请使用以下命令返回的绝对可执行文件路径：

bash

command -v pandanpc-mcp

在 Windows PowerShell 中，请使用：

powershell

Get-Command pandanpc-mcp

从代理登录

PandaNpc 使用两步电子邮件验证流程。请让代理按顺序执行以下操作：

使用您的电子邮件地址调用 note_login。PandaNpc 会发送一个验证码。
使用相同的电子邮件地址和该验证码再次调用 note_login。

本地凭据会被缓存，因此您无需在每次会话中都登录。切勿将验证码粘贴到公开的会话记录或共享的提示词中。

验证 MCP 连接

在允许代理创建或编辑数据之前，运行一个小的只读测试：

让它调用 list_workspaces。
让它为某个工作区调用 list_notes。
让它使用 search_notes 搜索一个无害的关键词。

成功的响应证明 MCP 客户端已启动该进程、身份验证已完成，并且账户 API 可访问。若要进行写入测试，请创建一个一次性笔记，然后将其软删除。

您的 MCP 客户端显示的确切工具列表是所安装版本的真实依据。工具围绕以下工作流分组：

工作流	典型工具	重要行为
笔记	`list_notes`, `create_note`, `read_note`, `update_note`, `search_notes`	`update_note` 会替换完整正文；编辑前请先读取
工作日志	`save_done`	自动将已完成的工作存储到今天的项目文件夹中
工作区	`list_workspaces`, `create_workspace`, `update_workspace`	绑定的项目路径让服务器找到正确的工作区
计划任务	`list_scheduled_bridges`, `create_scheduled_task`, `list_scheduled_task_runs`	PandaPaw 机器必须在线；cron 表达式使用六个字段
提供商和模型	`list_providers`, `list_models`, 创建/更新/删除工具	先列出列表，这样您能使用当前的 ID 和有效的模型类型
规则和技能	`sync_rules`	同步受支持的项目指令，同时跳过未更改的文件

关于提供商和模型字段定义，请参阅自定义 AI 提供商和 API keys。关于账户和计费限制，请参阅 PandaNpc 账户、套餐和 API 成本。

安全操作实践

在执行创建、更新、删除或计划操作之前，先使用列表、读取或搜索工具。
在更新笔记之前先读取笔记，因为笔记更新会替换整个 Markdown 文档，而不是应用补丁。
将计划提示视为代码执行请求：确认目标机器、工作目录、时区和六字段 cron 表达式。
将提供商的 API keys 放在提示词和笔记之外。仅通过预期的提供商配置流程输入机密信息。
在允许破坏性或外部操作之前，审查 MCP 工具批准卡片。
使用 save_done 记录工作日志，而不是手动猜测正确的工作区和日期文件夹。

故障排除

客户端提示找不到 `pandanpc-mcp`

安装后打开一个新的终端并检查可执行文件路径。桌面应用程序有时会继承较旧的 PATH；请配置绝对路径或重启应用程序。如果 npm 是通过版本管理器安装的，请确保 MCP 客户端在相同的用户和环境之下启动。

服务器已注册但没有工具出现

重启客户端，然后检查 claude mcp get pandanpc 或 codex mcp get pandanpc。如果命令错误，请移除并重新添加该条目。还要确认您没有将本地 stdio 进程配置为 HTTP URL。

工具提示您未通过身份验证

重复两次 note_login 调用。使用最新的验证码，检查垃圾邮件文件夹，并确认两次调用使用相同的电子邮件地址。

计划任务找不到机器

首先调用 list_scheduled_bridges。如果没有返回可用设备，请在目标机器上验证 PandaPaw 状态和设备连接。处于关机、休眠、已注销或断开连接状态的机器无法启动计划运行。

笔记更新删除了现有文本

update_note 接受完整的替换正文。请从笔记历史记录或回收站中恢复该笔记（如果可用），然后读取当前内容并提交合并后的文档。

需要特定于账户的帮助？请联系 support@pandanpc.com，并附上 MCP 客户端名称、操作系统、软件包版本和不含机密信息的确切错误消息。