# p4plan-mcp [Health: Active]

**Category:** 📋 Product Management  
**Repository:** https://github.com/perforce/p4plan-mcp.git  
**GitHub Stars:** 4  
**npm Downloads (last month):** 816  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/p4plan-mcp

## Description
MCP server for P4 Plan — tasks, sprints, bugs, comments, custom fields via GraphQL API.

## Tools
Capabilities this server exposes over MCP:

- **Parameters** — `projectId`
- **Types** — `backlog_task`, `bug`, `scheduled_task`, `sprint`, `release`, `sprint_task`

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "p4plan-mcp": {
    "command": "npx",
    "args": ["-y","@perforce/p4plan-mcp"],
    "env": {
      "P4PLAN_API_AUTH_TOKEN": "",
      "P4PLAN_API_URL": ""
    }
  }
}
```

**Requires environment variables:** `P4PLAN_API_AUTH_TOKEN`, `P4PLAN_API_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What p4plan-mcp does

p4plan-mcp connects AI assistants that support MCP with P4 Plan project-management data. Its toolset covers work items and planning records, including backlog tasks, scheduled tasks, sprint tasks, bugs, sprints, and releases. It also supports operations involving comments and custom fields through the P4 Plan GraphQL API.

The server is designed for projects where an assistant needs to inspect or update planning information without a separate bespoke integration. Tool calls can use a `projectId` parameter to identify the relevant P4 Plan project.

## How it works

An MCP client starts the server as a child process and communicates with it through standard input and output. The server does not maintain application state between calls; it translates MCP requests into GraphQL requests sent to the P4 Plan API.

Authentication uses a JWT supplied through `P4PLAN_API_AUTH_TOKEN`. That token is checked when the process starts and forwarded to the API as a bearer credential for tool requests. `P4PLAN_API_URL` identifies the API origin. The server adds the required GraphQL and related endpoint paths itself, so the value should be a base URL rather than a URL containing a path or trailing slash.

## Setup and configuration

Node.js 20 or newer and npm 9 or newer are supported prerequisites. The connected P4 Plan API must be version 2026.1.002 or later. The simplest launch method uses the npm package through `npx`:

```bash
npx -y @perforce/p4plan-mcp
```

Configure the MCP client to run that command and provide the required environment variables:

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

The package can also be built from a local checkout with `npm ci` followed by `npm run build`. Docker images are available as `perforce/p4plan-mcp`, and the image can be run as an MCP stdio process with the same environment variables.

Optional settings include `LOG_LEVEL`, `SEARCH_LIMIT`, `P4PLAN_ALLOW_SELF_SIGNED_CERTS`, and `P4PLAN_UPLOAD_DIRS`. The latter controls additional directories that attachment uploads may read, alongside folders shared by the MCP client.

## Tools and capabilities

The server provides 30 tools covering P4 Plan operations. Supported data types include:

- `backlog_task`
- `bug`
- `scheduled_task`
- `sprint`
- `release`
- `sprint_task`

The broader toolset handles task and planning records, comments, custom fields, links, commits, deletion, and attachment uploads. Search result size can be controlled with `SEARCH_LIMIT`, which defaults to 400.

## Limitations and notes

Read-only operation is available with the `--readonly` argument or `P4PLAN_READONLY=true`. In this mode, write-oriented tools are not registered, and requests are checked so that only plain GraphQL queries reach the API. This also prevents content retrieved from P4 Plan from directing the server to make changes.

The process is intended to be launched by an MCP client rather than used interactively in a terminal. For Docker connections to an API running on the host, the appropriate host address depends on the operating system: `host.docker.internal` is used on macOS and Windows, while Linux setups can use `172.17.0.1`.

The project is licensed under MIT and is published as the npm package `@perforce/p4plan-mcp` and the MCP Registry entry `io.github.perforce/p4plan-mcp`.

_Full upstream README: https://allmcps.com/mcp/p4plan-mcp/readme_