P4plan MCP

P4 Plan MCP Server

MCP (Model Context Protocol) server for P4 Plan, enabling AI assistants like Claude and VS Code Copilot to interact with P4 Plan project management data.

Architecture · Prerequisites · Quick Start · Install · Client Configurations · Tools

Skills · Logging · Troubleshoot · Development · License

Architecture

This service acts as a stateless protocol adapter between MCP clients (AI assistants) and the P4 Plan GraphQL API, using stdio transport (stdin/stdout).

┌─────────────────┐     stdio (stdin/stdout)    ┌─────────────────┐     GraphQL      ┌─────────────────┐

│ AI Client │ ────────────────────────▶ │ P4 Plan MCP │ ──────────────▶ │ P4 Plan GraphQL │ │(Claude, Copilot)│ Spawns as child process │ Server │ Port 4000 │ API │ │ │ P4PLAN_API_AUTH_TOKEN │ (stateless) │ Bearer token │ │ └─────────────────┘ env var └─────────────────┘ forwarded └─────────────────┘

The client spawns the MCP server as a child process. Authentication is provided via the P4PLAN_API_AUTH_TOKEN environment variable, which the server validates at startup and forwards to the GraphQL API on every tool call.

Prerequisites

Tip: Use nvm to manage Node.js versions, or skip the Node.js requirement entirely by using Docker.

Quick Start (npx)

The fastest way to get started — no installation required. Just configure your MCP client to use npx:

npx -y @perforce/p4plan-mcp

npx automatically downloads and runs the latest version of the server. Your MCP client (VS Code, Claude Desktop, etc.) handles this for you — just add the config below and start chatting.

VS Code — add to .vscode/mcp.json:

{

"servers": { "p4-plan": { "type": "stdio", "command": "npx", "args": ["-y", "@perforce/p4plan-mcp"], "env": { "P4PLAN_API_AUTH_TOKEN": "YOUR_JWT_TOKEN", "P4PLAN_API_URL": "http://localhost:4000" } } } }

Claude Desktop — add to your config:

{

"mcpServers": { "p4-plan": { "command": "npx", "args": ["-y", "@perforce/p4plan-mcp"], "env": { "P4PLAN_API_AUTH_TOKEN": "YOUR_JWT_TOKEN", "P4PLAN_API_URL": "http://localhost:4000" } } } }

Note: The -y flag auto-confirms the npm install prompt so the server starts without user interaction.

See Client Configuration for more options including Docker, secure token prompts, and local builds.

MCP Registry

This server is published to the official MCP Registry as `io.github.perforce/p4plan-mcp`. Discover it via the registry API:

curl 'https://registry.modelcontextprotocol.io/v0/servers?search=io.github.perforce/p4plan-mcp'

MCP clients that support registry discovery can install the server by name without needing to know the npm package identifier.

Installation

Build from source

For development or when you want to run from a local clone:

npm ci

npm run build

For using npx locally

npm link

Run from Docker

Run the MCP server via Docker instead of installing Node.js locally. The MCP client (VS Code, Claude Desktop) spawns the container as a child process — same as npx, just using docker as the command.

The image is published to Docker Hub at perforce/p4plan-mcp, built multi-arch (linux/amd64 + linux/arm64) on every release, with SLSA provenance and SBOM attestations.

VS Code (.vscode/mcp.json):

{

"servers": { "p4-plan": { "type": "stdio", "command": "docker", "args": [ "run", "-i", "--rm", "-e", "P4PLAN_API_AUTH_TOKEN=YOUR_JWT_TOKEN", "-e", "P4PLAN_API_URL=http://host.docker.internal:4000", "perforce/p4plan-mcp:latest" ] } } }

Claude Desktop:

{

"mcpServers": { "p4-plan": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "P4PLAN_API_AUTH_TOKEN=YOUR_JWT_TOKEN", "-e", "P4PLAN_API_URL=http://host.docker.internal:4000", "perforce/p4plan-mcp:latest" ] } } }

Note: Use host.docker.internal (macOS/Windows) or 172.17.0.1 (Linux) to reach the P4 Plan GraphQL API running on the host machine.

Pin a specific version by replacing :latest with :2026.3.2 (or whichever tag) for reproducible deployments.

Build locally (for development against unreleased changes):

docker build -t p4plan-mcp:dev .

then swap "perforce/p4plan-mcp:latest" for "p4plan-mcp:dev" in the configs above

Configuration

Copy the example config and configure:

cp config-example.env .env

Edit .env with your settings:

# JWT token for authenticating with P4 Plan GraphQL API

Obtain via: login mutation on the GraphQL API

P4PLAN_API_AUTH_TOKEN=your-jwt-token

P4 Plan GraphQL API URL — base origin only. Do not include a path or a

trailing slash: the server appends /graphql, /healthcheck and /attachment/

itself, so a trailing slash produces //graphql.

P4PLAN_API_URL=https://p4plan-api.example.com

Logging

LOG_LEVEL=info

Maximum number of results returned by search_tasks (default: 400)

SEARCH_LIMIT=400

Allow self-signed TLS certificates when connecting to the P4 Plan API over HTTPS

Set to true if your API uses a self-signed or untrusted certificate

P4PLAN_ALLOW_SELF_SIGNED_CERTS=true

Read-only mode: expose only the tools that read (same as the --readonly argument)

P4PLAN_READONLY=true

Folders upload_attachment may read files from, besides the workspace folders

the MCP client shares. Separate several with ":" (";" on Windows)

P4PLAN_UPLOAD_DIRS=/Users/me/Screenshots:/Users/me/logs

The server communicates via stdin/stdout. It is not meant to be run interactively — MCP clients (VS Code, Claude Desktop) spawn it as a child process automatically.

Read-only mode

Start the server with the --readonly argument, or set P4PLAN_READONLY=true, to make it read-only:

• Only the tools that read are registered. Tools that create, update, comment, link, commit or delete are not offered to the model at all.
• As a second layer, every GraphQL request a tool makes is checked, and only plain queries are sent to the P4 Plan API. Mutations, subscriptions and anything that cannot be classified are refused.
• The model is told that changes are not available, so it explains this instead of trying. The skills that are only about writing (comment-html-format, mentions) are left out.

This means content read from P4 Plan (a task description or a comment, for example) cannot steer the model into changing data through this server.

{

"servers": { "p4-plan": { "type": "stdio", "command": "npx", "args": ["-y", "@perforce/p4plan-mcp", "--readonly"], "env": { "P4PLAN_API_AUTH_TOKEN": "YOUR_JWT_TOKEN", "P4PLAN_API_URL": "http://localhost:4000" } } } }

With Docker, pass -e P4PLAN_READONLY=true or put --readonly after the image name. With Docker Compose, set P4PLAN_READONLY=true in your shell or .env; docker-compose.yml passes it to the container.

Read-only mode limits what the MCP server does; it does not change what the token may do. For the strongest guarantee, also authenticate as a P4 Plan user that only has read access.

Uploading files

upload_attachment attaches a local file, or text the model writes, to a task, bug, sprint or release. Reading local files would let a prompt injection ask for something like ~/.ssh/id_rsa, so the server only reads files inside allowed folders:

• the workspace folders your MCP client shares with the server (MCP roots), and
• the folders listed in P4PLAN_UPLOAD_DIRS (separate several with :, or ; on Windows).

Symlinks are resolved before the check, hidden files and folders (names starting with ., such as .env, .ssh or .git) are never uploaded, and only regular files are read. If the client shares no folders and P4PLAN_UPLOAD_DIRS is not set, only text uploads (content + fileName) work.

With Docker the container cannot see your files: mount a folder and point P4PLAN_UPLOAD_DIRS at the path inside the container, for example -v "$HOME/Screenshots:/uploads:ro" -e P4PLAN_UPLOAD_DIRS=/uploads, and pass paths such as /uploads/bug.png.

The file is streamed to the P4 Plan API (POST /attachment/ /upload), so its content never passes through the model. The P4 Plan server's own limits apply: its attachment size limit and blocked file types. If a file with the same name is already attached, the server stores the new one as name (1).ext. If an upload times out it may still have completed, so check get_attachments before retrying.

To show an image inside a comment or a multiline field (bug description, steps to reproduce, Multiline Text columns), upload it to the same item and put the returned imageHtml ( ) in the HTML. This is how the P4 Plan clients embed pasted images; the server turns images with any other src into plain links.

So that one client cannot flood the P4 Plan API (a model stuck in a loop, or a prompt injection asking for many files), each MCP server runs its uploads one at a time and starts at most 20 uploads per minute. Further calls get an error saying how long to wait.

Every tool publishes MCP tool annotations. readOnlyHint marks the tools that only read; tools that write also carry destructiveHint (the call deletes or overwrites data) and idempotentHint. Clients that support annotations can use them to ask for confirmation before a write.

Authentication

The MCP server requires a JWT token provided via the P4PLAN_API_AUTH_TOKEN environment variable. The token is validated at startup and forwarded to the P4 Plan GraphQL API on every tool call. No sessions or state are maintained.

Obtaining a JWT Token

Get a JWT token from the P4 Plan GraphQL API using curl. You can authenticate with either your password or a Personal Access Token (PAT):

Usi