Allows AI assistants to manage project data including tasks, sprints, bugs, and comments via the P4 Plan GraphQL API.
Also known as perforce/p4plan-mcp, @perforce/p4plan-mcp
- Stars
- 4
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- 2026.3.2
- Last commit
- Oct 22, 2026
- License
- MIT
What is P4 Plan MCP?
P4 Plan allows AI assistants to manage project data including tasks, sprints, bugs, and comments via the P4 Plan GraphQL API.
Summary generated from the project's README
About P4 Plan MCP server
Managing project data like tasks, sprints, bugs, and comments directly from an AI assistant is what p4plan-mcp enables. This stateless protocol adapter connects MCP clients, such as Claude Desktop or VS Code Copilot, to the P4 Plan GraphQL API using stdio transport. It allows developers to interact with their project management workflows without leaving their coding environment.
To use this server, you must provide a P4PLAN_API_AUTH_TOKEN via an environment variable and specify the P4PLAN_API_URL. The server can be run locally using npx or via Docker containers. For increased security, a read-only mode is available which restricts the model to query-only operations, preventing any mutations or deletions. The server also supports uploading attachments to tasks or bugs, provided the files are located within shared workspace folders or directories defined in the P4PLAN_UPLOAD_DIRS setting.
What you can do with it
- 1Update project task detailsAn AI assistant can modify existing tasks or add comments to bug reports within your project management system.
- 2Attach files to bugsYou can instruct an AI to upload a local screenshot or log file directly to a specific bug or sprint.
Written from the project's README. Every use case is checked against a quote from it.
How to install P4 Plan MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall P4 Plan MCP in Claude Code
$ claude mcp add --env 'P4PLAN_API_AUTH_TOKEN=<YOUR_P4PLAN_API_AUTH_TOKEN>' p4plan-mcp -- npx -y @perforce/p4plan-mcpInstall P4 Plan MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"p4plan-mcp": {
"command": "npx",
"args": [
"-y",
"@perforce/p4plan-mcp"
],
"env": {
"P4PLAN_API_AUTH_TOKEN": "<YOUR_P4PLAN_API_AUTH_TOKEN>"
}
}
}
}Install P4 Plan MCP in VS Code
.vscode/mcp.json
{
"servers": {
"p4plan-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@perforce/p4plan-mcp"
],
"env": {
"P4PLAN_API_AUTH_TOKEN": "<YOUR_P4PLAN_API_AUTH_TOKEN>"
}
}
}
}Install P4 Plan MCP in VS Code CLI
$ code --add-mcp '{"name":"p4plan-mcp","type":"stdio","command":"npx","args":["-y","@perforce/p4plan-mcp"],"env":{"P4PLAN_API_AUTH_TOKEN":"<YOUR_P4PLAN_API_AUTH_TOKEN>"}}'Install P4 Plan MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"p4plan-mcp": {
"command": "npx",
"args": [
"-y",
"@perforce/p4plan-mcp"
],
"env": {
"P4PLAN_API_AUTH_TOKEN": "<YOUR_P4PLAN_API_AUTH_TOKEN>"
}
}
}
}Install P4 Plan MCP in Codex
$ codex mcp add p4plan-mcp --env 'P4PLAN_API_AUTH_TOKEN=<YOUR_P4PLAN_API_AUTH_TOKEN>' --env 'P4PLAN_API_AUTH_TOKEN=<YOUR_P4PLAN_API_AUTH_TOKEN>' -- npx -y @perforce/p4plan-mcpInstall P4 Plan MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.p4plan-mcp] command = "npx" args = ["-y", "@perforce/p4plan-mcp"] [mcp_servers.p4plan-mcp.env] P4PLAN_API_AUTH_TOKEN = "<YOUR_P4PLAN_API_AUTH_TOKEN>"
Install P4 Plan MCP in Gemini CLI
$ gemini mcp add -s user -e 'P4PLAN_API_AUTH_TOKEN=<YOUR_P4PLAN_API_AUTH_TOKEN>' -e 'P4PLAN_API_AUTH_TOKEN=<YOUR_P4PLAN_API_AUTH_TOKEN>' p4plan-mcp npx -- -y @perforce/p4plan-mcpInstall P4 Plan MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"p4plan-mcp": {
"command": "npx",
"args": [
"-y",
"@perforce/p4plan-mcp"
],
"env": {
"P4PLAN_API_AUTH_TOKEN": "<YOUR_P4PLAN_API_AUTH_TOKEN>"
}
}
}
}Configuration
P4PLAN_API_AUTH_TOKENRequiredSecretJWT bearer token for the P4 Plan GraphQL API. Forwarded as Authorization on every tool call.
P4PLAN_API_AUTH_TOKENRequiredSecretJWT bearer token for the P4 Plan GraphQL API. Forwarded as Authorization on every tool call.
LOG_LEVELP4PLAN_ALLOW_SELF_SIGNED_CERTSSet to 'true' to accept self-signed TLS certificates from the GraphQL API. Default: false.
P4PLAN_ALLOW_SELF_SIGNED_CERTSSet to 'true' to accept self-signed TLS certificates from the GraphQL API. Default: false.
P4PLAN_API_URLURL of the P4 Plan GraphQL API (default: http://localhost:4000).
P4PLAN_API_URLURL of the P4 Plan GraphQL API (default: http://localhost:4000).
P4PLAN_READONLYSet to 'true' to expose only the tools that read (same as the --readonly argument). Default: false.
P4PLAN_READONLYSet to 'true' to expose only the tools that read (same as the --readonly argument). Default: false.
P4PLAN_UPLOAD_DIRSFolders upload_attachment may read files from, besides the workspace folders the MCP client shares. Separate several with ':' (';' on Windows).
P4PLAN_UPLOAD_DIRSFolders upload_attachment may read files from, besides the workspace folders the MCP client shares. Separate several with ':' (';' on Windows).
| Name | Description | |
|---|---|---|
| P4PLAN_API_AUTH_TOKEN | JWT bearer token for the P4 Plan GraphQL API. Forwarded as Authorization on every tool call. | RequiredSecret |
| P4PLAN_API_AUTH_TOKEN | JWT bearer token for the P4 Plan GraphQL API. Forwarded as Authorization on every tool call. | RequiredSecret |
| LOG_LEVEL | — | |
| P4PLAN_ALLOW_SELF_SIGNED_CERTS | Set to 'true' to accept self-signed TLS certificates from the GraphQL API. Default: false. | |
| P4PLAN_ALLOW_SELF_SIGNED_CERTS | Set to 'true' to accept self-signed TLS certificates from the GraphQL API. Default: false. | |
| P4PLAN_API_URL | URL of the P4 Plan GraphQL API (default: http://localhost:4000). | |
| P4PLAN_API_URL | URL of the P4 Plan GraphQL API (default: http://localhost:4000). | |
| P4PLAN_READONLY | Set to 'true' to expose only the tools that read (same as the --readonly argument). Default: false. | |
| P4PLAN_READONLY | Set to 'true' to expose only the tools that read (same as the --readonly argument). Default: false. | |
| P4PLAN_UPLOAD_DIRS | Folders upload_attachment may read files from, besides the workspace folders the MCP client shares. Separate several with ':' (';' on Windows). | |
| P4PLAN_UPLOAD_DIRS | Folders upload_attachment may read files from, besides the workspace folders the MCP client shares. Separate several with ':' (';' on Windows). |
Automated checks
Ran Nov 13, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablePass
- Open source license (OSI)Pass
- Commit or release in the last yearPass
- Package name not close to a popular packagePass
- Remote endpoint uses HTTPSNot checked
- Destructive tools are labelledNot checked
- No hidden instructions to the modelPass
- No critical advisory in the package or its dependenciesPass
README
View on GitHub
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
| Requirement | Version | Notes |
|---|---|---|
| Node.js | >= 20 (24+ recommended) | The server targets ES2023. Check with node -v. |
| npm | >= 9 | Comes with Node.js. Check with npm -v. |
| P4 Plan API | >= 2026.1.002 | Required for all tool operations. Earlier versions are not supported. |
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
-yflag 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
For development or when you want to run from a local clone:
npm ci
npm run build
# For using npx locally
npm link
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) or172.17.0.1(Linux) to reach the P4 Plan GraphQL API running on the host machine.
Pin a specific version by replacing
:latestwith: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/<id>
# 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/<id>/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 (<img src="hansoft://...">) 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):
curl -s -X POST http://localhost:4000/graphql \
-H "Content-Type: application/json" \
-d '{
"query": "mutation Login($loginUserInput: LoginUserInput!) { login(loginUserInput: $loginUserInput) { access_token } }",
"variables": { "loginUserInput": { "username": "YOUR_USERNAME", "password": "YOUR_PASSWORD" } }
}'
A PAT can be used in place of your password in the same login mutation. This avoids exposing your actual password:
curl -s -X POST http://localhost:4000/graphql \
-H "Content-Type: application/json" \
-d '{
"query": "mutation Login($loginUserInput: LoginUserInput!) { login(loginUserInput: $loginUserInput) { access_token } }",
"variables": { "loginUserInput": { "username": "YOUR_USERNAME", "password": "YOUR_PERSONAL_ACCESS_TOKEN" } }
}'
Both methods return the same response:
{
"data": {
"login": {
"access_token": "eyJhbGciOiJIUzI1NiIs..."
}
}
}
Copy the access_token value and use it in your MCP client configuration.
- Log in to P4 Plan
- Go to User Settings → Personal Access Tokens
- Click Generate New Token
- Set an appropriate expiration date
- Copy the token — use it in the login mutation above to obtain a JWT
Note: JWT tokens expire. When your token expires, the server will fail to start with an authentication error. Generate a new JWT using the same
curlcommand above.
Available Tools (31 total)
Tool arguments are parsed leniently, so less capable models succeed more often. Enum values match regardless of case, spaces, _ or - ("Time Spent" → timeSpent). "true"/"yes" are accepted for booleans, numbers for IDs, numeric strings for numbers, and JSON-encoded lists or comma-separated ID lists. Anything that can't be mapped unambiguously is rejected with the allowed values.
Projects
- Use cases: Discover project IDs needed by other tools
- Parameters:
projectId - Use cases: Retrieve section IDs (backlog, QA, planning) for other tools
- Parameters:
name, optionalmethodTemplate,defaultMode,members(user or global group names/IDs),managers(normal user names/IDs),addMeAsManager(default true), orcopyFromProjectIdwithcopyUsers/copyColumnsto base it on an existing project - Use cases: Stand up a new project for a team without the UI. Requires P4 Plan administrator rights; steps that fail after the project is created are listed in
failed
Tasks
- Parameters:
showCompleted,showOnlyNextFourWeeks,showHidden,showPipelineTasksThatCannotStart - Use cases: View personal work queue across all projects
- Parameters:
taskIds(array of strings, max 20) -- database item IDs, i.e. theidreturned by other tools - Every item response includes both
id(the database ID that all tools take) andlocalID(the number shown in the P4 Plan UI's "ID" column). - Use cases: Full item details, link inspection, batch retrieval of multiple items
- Parameters:
findQuery,projectId - Uses P4 Plan Find query syntax for all searches. Call
read_skillwithskillName="search-queries"first to get exact column names, operators, and value formats. For simple name search useItemname:Text("text"). Supports filtering by status, assignee, severity, item type, dates, boolean conditions, and combinations with AND/OR/NOT. - Each project has three sections (Backlog, QA, Planning) with different IDs.
- To resolve an ID, query it directly:
ID=<n>matches the UI "ID" column (the local ID, unique only within a section) andDatabaseid=<n>matches the database ID. - Use cases: Item discovery, filtering, reporting
- Types:
backlog_task,bug,scheduled_task,sprint,release,sprint_task - Parameters:
type,name,projectId,parentItemId,previousItemId, and type-specific fields - Use cases: Task creation, sprint creation, bug filing
- Types: BacklogTask, Bug, ScheduledTask, Sprint, Release
- Parameters:
itemId, plus any updatable fields (name, status, assignedTo, points, etc.) - Use cases: Status updates, assignments, estimation, sprint configuration
Sprint & Release Management
- Parameters:
taskId,sprintId - Use cases: Sprint planning, backlog commitment
- Parameters:
taskId - Use cases: Sprint scope adjustment
Custom Fields & Workflows
- Parameters:
projectId - Use cases: Discover custom fields before reading/writing values
- Parameters:
projectId(planning, backlog or QA ID),name,columnType,activated,readOnly, plus type-specificunitName,updateOn*/updateOnlyFirstTime,useForTimeReporting/updateWorkRemaining,dropListItems(labels, or objects withicon,autoAssignToUsers,autoAssignToUserGroups) - Use cases: Set up a project's columns without the UI. Requires main project manager rights
- Parameters:
taskId,onlySet - Use cases: Read project-specific metadata
- Parameters:
taskId,customFieldId,value - Use cases: Update project-specific metadata
- Parameters:
projectId - Use cases: Discover workflow statuses for status transitions
Task Actions
- Parameters:
taskId - Use cases: Quick status update convenience method
- Parameters:
taskId - Use cases: Quick status update convenience method
Comments & Attachments
- Parameters:
taskId - Use cases: Read discussion history
- Parameters:
taskId,text - Use cases: Add discussion, acceptance criteria, notes
- Parameters:
taskId,commentId,text - Use cases: Correct or update existing comments
- Parameters:
taskId,commentId - Use cases: Remove outdated or incorrect comments
- Parameters:
taskId - Use cases: List attached files, discover paths for download
- Parameters:
taskId,path - Text files returned inline, images as base64
- Use cases: Read attached documents, view screenshots
- Parameters:
taskId, and eitherfilePath(optionallyfileNameto rename it) orcontent+fileName - Local files must be inside an allowed folder, see Uploading files
- Returns the new attachment
path; the first image attached becomes the cover image - For images it also returns
imageHtml, an<img>tag that shows the image inside a comment, description, steps to reproduce or Multiline Text field of the same item - Use cases: Attach screenshots, logs or repro files to bug reports and user stories
- Parameters:
taskId,path - Use cases: Remove outdated attachments
- Parameters:
taskId,imagePath - Use cases: Set visual identity for cards/items
Links
- Parameters:
fromItemId,toItemIdorurl,relation(blocks, duplicates, relatedTo) - Use cases: Dependency tracking, cross-references, external URLs
- Parameters:
fromItemId,toItemIdorurl - Use cases: Clean up outdated dependencies
Users
- Use cases: Identity verification, user context
- Parameters:
projectId - Use cases: Find user IDs for assignments, sprint member management
P4 Plan MCP questions
How do I add P4 Plan MCP to Claude Code?
Run claude mcp add --env 'P4PLAN_API_AUTH_TOKEN=<YOUR_P4PLAN_API_AUTH_TOKEN>' p4plan-mcp -- npx -y @perforce/p4plan-mcp in your terminal. Add --scope user to make it available in every project.
How do I add P4 Plan MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
How do I authenticate with the P4 Plan MCP server?
Authentication is handled by providing a JWT token through the P4PLAN_API_AUTH_TOKEN environment variable.
Can I run the server in a mode that prevents data modification?
Yes, you can enable read-only mode using the --readonly argument or by setting the P4PLAN_READONLY environment variable to true.
Can I use Docker to run the server?
Yes, you can run the MCP server via Docker instead of installing Node.js locally using the perforce/p4plan-mcp image.