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 (about once an hour with random jitter; failed checks back off exponentially from 15 minutes up to 6 hours). It downloads the platform binary into the user's cache, verifies SHA-256 and runs a bounded startup check, which stages it as a candidate. The launcher stays between the MCP client and the runtime, so a running session switches to the candidate without a restart: it completes a real MCP handshake with the client's own initialize request, waits for in-flight requests to finish (new requests are queued in order), then closes the old runtime. A new runtime becomes the default for future sessions only after it has served a tool call or run for a minute; one that fails to start, times out or crashes before that is skipped with a growing backoff, and a session whose new runtime crashes, before or after that point, goes back to the previous runtime automatically (requests that were in flight get an error and are not replayed). The crashed version is not retried in that session and is skipped with the same backoff; if it had already become the default, later sessions start from the runtime it replaced. If the new version changes the tool list, Claude Code sessions switch and receive notifications/tools/list_changed; other clients keep the current runtime and use the new one from their next session. A change to the server instructions always waits for the next session, because clients cannot refresh instructions mid-session; a switch is also postponed while the client is not reading the launcher's output. The launcher always advertises tools.listChanged to the client, even when the runtime does not declare it (runtimes 0.1.45 and earlier never do), so a later switch can still refresh the tool list. Offline or failed updates keep the existing runtime usable. Sessions that were started by an older launcher (0.1.45 or earlier) cannot switch in place: after upgrading the npm package, reconnect the MCP server (or restart the session) once; later releases then apply to running sessions automatically.

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; running sessions pick up the result within a minute when compatible. 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.