PandaNpc MCP Server — expose PandaNote, workspaces, AI models, scheduled tasks, and Agent connection management to Codex, Claude Code, Cursor, Windsurf, and other MCP clients.

Installation

npm install -g @pandanpc/mcp-server

The postinstall script downloads the matching Rust binary for your platform from https://cos.pandanpc.com/mcp-server/.

Supported platforms

Linux x64
macOS x64 (Intel)
macOS arm64 (Apple Silicon)
Windows x64

Claude Code configuration

Edit ~/.config/claude-code/config.json (or the platform equivalent):

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

CLI usage

# stdio mode (default for MCP clients)
pandanpc-mcp

# HTTP/SSE mode
pandanpc-mcp --http --port 3100

Codex configuration

Add this to ~/.codex/config.toml:

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

Available tools

get_guide — load only the workflow needed: notes, layouts, schedules, mail, memory or ASC
note_layout_guide — choose and write native image galleries (also available as get_guide topic layouts)
note_login — log in to your PandaNpc account
list_workspaces / create_workspace / update_workspace / delete_workspace
list_notes / create_note / read_note / update_note / delete_note / move_note_to_workspace
search_notes — title + full-text + semantic search
generate_note_title — AI-generated title and icon
list_providers / create_provider / update_provider / delete_provider
list_models / list_model_types / create_model / update_model / delete_model
list_agent_connections — inspect Claude Code / Codex / PandaCode connections without exposing relay tokens
create_agent_connection — idempotently create a connection; current-machine PandaPaw credentials are auto-detected
list_scheduled_tasks / create_scheduled_task / update_scheduled_task / toggle_scheduled_task / delete_scheduled_task
sync_rules — sync .claude/rules/ and .claude/skills/ Markdown files to PandaNote

Account operations require note_login when not already authenticated. Reading guides does not require a note login.

Automatic runtime updates

The npm launcher starts the last verified runtime immediately and checks for a newer stable release in a separate background process (at most once every six hours; failed checks back off for 15 minutes). It downloads the platform binary into the user's cache, verifies SHA-256, and runs a bounded startup check before atomically selecting it for the next launch. Current MCP sessions are never restarted or replaced. Offline or failed updates keep the existing runtime usable.

The cache defaults to ~/.pandanpc-mcp/runtime/<platform>-<arch> and does not require write access to a global npm installation. Each version uses its own file, including on Windows. Older cached executables are retained because another session may still use them; remove the cache only after closing those sessions if you want to reclaim disk space.

pandanpc-mcp --version shows the selected runtime and npm launcher versions.
pandanpc-mcp --update checks/downloads now; reconnect afterwards to use the result. Status messages go to stderr, never the MCP protocol stream.
Set PANDANPC_MCP_AUTO_UPDATE=0 in the MCP client's environment to disable checks and pin the runtime bundled with the installed npm version.
PANDANPC_MCP_CACHE_DIR optionally selects a different user-writable cache directory.

Existing users must first upgrade to a launcher containing this feature with npm install -g @pandanpc/mcp-server@latest, then reconnect. Automatic updates cover the executable and its embedded guides, not the npm launcher code or separately copied Skill files. A future release requiring a different updater protocol must be installed through npm; --update reports that condition. Directly launching a downloaded Rust binary bypasses the npm updater.

Optional Agent Skill

The package includes skills/pandanpc/SKILL.md and its references. These are the same guide files embedded in the MCP binary, so examples stay aligned with the installed version. MCP-only clients can call get_guide; they do not need filesystem or Skill support.

For a client that supports Agent Skills, explicitly install/copy the package's skills/pandanpc directory to that client's supported skill location. For a global npm installation, the package is under npm root -g plus @pandanpc/mcp-server. Consult your client's skill discovery settings, and refresh this optional copy when updating the MCP. The npm installer does not modify user/project skill directories automatically.

The bundled skill covers public PandaNpc workflows only; it does not contain project-specific machine settings or credentials.