Perforce P4 Mcp Server

Perforce P4 MCP Server is a Model Context Protocol (MCP) server that integrates with the Perforce P4 version control system. It is built on FastMCP with direct P4 Python bindings to expose safe, structured read/write tools for changelists, files, shelves, workspaces, jobs, reviews, and server metadata.

Features·Prerequisites·System Requirements·Install·Deployment·Client Configurations·P4 Configurations·Tools

Logging·Troubleshoot·Support·Contributions·License

If you haveuvinstalled, you can run P4 MCP Server directly without any manual installation:

# Run the server uvx p4mcp-server # Check version uvx p4mcp-server --version # Run with arguments uvx p4mcp-server --readonly --allow-usage

- uvinstalled on your system
- Python 3.11+ (uv will handle this automatically)

- macOS:p4-mcp-server-mac.zip
- Windows:p4-mcp-server-win.zip
- Linux:p4-mcp-server-linux.zip

# macOS / Linux unzip p4-mcp-server-mac.zip # or p4-mcp-server-linux.zip ./p4-mcp-server --help

# Windows Expand-Archive p4-mcp-server-win.zip -DestinationPath . .\p4-mcp-server.exe --help

{ "mcpServers": { "perforce-p4-mcp": { "command": "/absolute/path/to/p4-mcp-server", "env": { "P4PORT": "ssl:perforce.example.com:1666", "P4USER": "your_username", "P4CLIENT": "your_workspace" }, "args": [ "--readonly", "--allow-usage" ] } } }

Note:This example shows explicitenvvalues. IfP4CONFIGis set, you can omit them and use the generic configuration example in theMCP client configurationsection instead.

Run the P4 MCP Server from a Docker container with STDIO transport, allowing MCP clients to manage the container lifecycle.

Note:Docker-based execution is currently supported on macOS and Linux only.

- Docker installed and running
- Valid P4 credentials and access to a P4 server

docker pull ghcr.io/perforce/p4mcp-server:latest

cd /path/to/p4mcp-server docker build -t ghcr.io/perforce/p4mcp-server .

{ "servers": { "perforce-p4mcp-docker": { "command": "docker", "args": [ "run", "-i", "--rm", "--hostname", "your-hostname", "-e", "P4PORT=ssl:perforce.example.com:1666", "-e", "P4USER=your_username", "-e", "P4CLIENT=your_workspace", "-v", "/Users/your_username/.p4tickets:/home/mcpuser/.p4tickets:ro", "ghcr.io/perforce/p4mcp-server:latest" ] } } }

# macOS/Linux -v /Users/your_username/.p4tickets:/home/mcpuser/.p4tickets:ro

Note:Use the full path to your tickets file (not~). After runningp4 login, restart the MCP server to pick up the new ticket.

⚠️Important:Docker containers have their own hostname, which differs from your local machine. If your P4 workspace is restricted to a specific host, operations likesyncwill fail.

To resolve this, set the container hostname to match your workspace's host restriction:

# macOS/Linux p4 client -o your_workspace | grep "^Host:"

Mounting Client Root for Write Operations

⚠️Important:By default, the Docker container cannot access your local workspace files. For write operations likesync,submit, orreconcile, you must mount your client root directory into the container at thesame path.

Add a volume mount for your client root:

-v /path/to/your/client/root:/path/to/your/client/root

Example configuration with client root mounted:

{ "servers": { "perforce-p4mcp-docker": { "command": "docker", "args": [ "run", "-i", "--rm", "--hostname", "your-hostname", "-e", "P4PORT=ssl:perforce.example.com:1666", "-e", "P4USER=your_username", "-e", "P4CLIENT=your_workspace", "-v", "/Users/your_username/.p4tickets:/home/mcpuser/.p4tickets", "-v", "/path/to/client/root:/path/to/client/root", "ghcr.io/perforce/p4mcp-server:latest" ] } } }

p4 client -o your_workspace | grep "^Root:"

Note:The mount path inside the container must match the client root path exactly, as P4 tracks files by their absolute paths.

Run the MCP server on a VM using the HTTP transport, allowing clients to connect over the network.

P4PORT=ssl:perforce.example.com:1666 P4USER=your_username P4PASSWD=YOUR_TICKET ./p4-mcp-server --readonly --transport http --port 8000

{ "servers": { "perforce-p4-mcp": { "type": "http", "url": "http://<ip-or-hostname>:8000/mcp" } } }

Note:Ensure the VM's firewall allows inbound connections on the chosen port. For production use, consider placing the server behind a reverse proxy with TLS.

Run the MCP server in a Docker container using HTTP transport and expose the MCP endpoint over a host port.

docker run --rm -p 8000:8000 \ -e P4PORT=ssl:perforce.example.com:1666 \ -e P4USER=your_username \ -e P4PASSWD=YOUR_TICKET \ ghcr.io/perforce/p4mcp-server:latest \ python3 -m p4mcp.main --readonly --transport http --port 8000

{ "servers": { "perforce-p4-mcp": { "type": "http", "url": "http://<ip-or-hostname>:8000/mcp" } } }

Note:Docker supports HTTP-based deployment as well. The container image defaults to STDIO transport, so the HTTP startup command must explicitly override the default command. If you need write operations, also mount the client root and ticket file paths into the container.

Note:In all configuration examples below, ifP4CONFIGis set, you do not need to set any environment variables in theenvblock. The server will use the configuration from the specified P4CONFIG file instead.

Tip:If you haveuvinstalled, you can useuvx p4mcp-serverinstead of/absolute/path/to/p4-mcp-serverin thecommandfield. This eliminates the need to download or build binaries manually.

{ "mcpServers": { "perforce-p4-mcp": { "command": "uvx", "args": [ "p4mcp-server", "--readonly", "--allow-usage" ], "env": { "P4PORT": "ssl:perforce.example.com:1666", "P4USER": "your_username", "P4CLIENT": "your_workspace" } } } }

{ "mcpServers": { "perforce-p4-mcp": { "command": "/absolute/path/to/p4-mcp-server", "env": { }, "args": [ "--readonly", "--allow-usage" ] } } }

See theJetBrains AI Assistant VCS Integration documentationfor detailed configuration steps.

See theClaude Code MCP docsfor more information.

{ "mcpServers": { "perforce-p4-mcp": { "command": "uvx", "args": [ "p4mcp-server", "--readonly", "--allow-usage" ], "env": { "P4PORT": "ssl:perforce.example.com:1666", "P4USER": "your_username", "P4CLIENT": "your_workspace" } } } }

{ "mcpServers": { "perforce-p4-mcp": { "command": "/absolute/path/to/p4-mcp-server", "env": { "P4PORT": "ssl:perforce.example.com:1666", "P4USER": "your_username", "P4CLIENT": "your_workspace" }, "args": [ "--readonly", "--allow-usage" ] } } }

See theCursor MCP documentationfor more information.

{ "mcpServers": { "perforce-p4-mcp": { "command": "/absolute/path/to/p4-mcp-server", "env": { "P4PORT": "ssl:perforce.example.com:1666", "P4USER": "your_username", "P4CLIENT": "your_workspace" }, "args": [ "--readonly", "--allow-usage" ] } } }

See theEclipse MCP documentationfor more information.

{ "servers": { "perforce-p4-mcp": { "command": "/absolute/path/to/p4-mcp-server", "env": { "P4PORT": "ssl:perforce.example.com:1666", "P4USER": "your_username", "P4CLIENT": "your_workspace" }, "args": [ "--readonly", "--allow-usage" ] } } }

See theKiro MCP documentationfor more information.

{ "mcpServers": { "perforce-p4-mcp": { "command": "/absolute/path/to/p4-mcp-server", "env": { "P4PORT": "ssl:perforce.example.com:1666", "P4USER": "your_username", "P4CLIENT": "your_workspace" }, "args": [ "--readonly", "--allow-usage" ] } } }

See theVS Code documentationfor more information.

{ "servers": { "perforce-p4-mcp": { "command": "/absolute/path/to/p4-mcp-server", "env": { "P4PORT": "ssl:perforce.example.com:1666", "P4USER": "your_username", "P4CLIENT": "your_workspace" }, "args": [ "--readonly", "--allow-usage" ] } } }

See theWindsurf MCP documentationfor more information.

{ "mcpServers": { "perforce-p4-mcp": { "command": "/absolute/path/to/p4-mcp-server", "env": { "P4PORT": "ssl:perforce.example.com:1666", "P4USER": "your_username", "P4CLIENT": "your_workspace" }, "args": [ "--readonly", "--allow-usage" ] } } }

- P4PORT- P4 Server address. Examples:ssl:perforce.example.com:1666,localhost:1666
- P4USER- Your P4 username
- P4CLIENT- Your current P4 workspace. Optional, but recommended

- P4MCP_MAX_RESULTS- Cap on the number of rows the P4 server returns per command (p4.maxresults). Default:10000. Set to0to disable the limit (server default in effect). When a command would exceed this limit the server aborts it with an error rather than truncating results, so keep the value generous. Can be overridden by the--max-resultsCLI argument. Must be a non-negative integer; an invalid value fails fast at startup before any P4 connection is attempted.
- P4MCP_MAX_SCAN_ROWS- Cap on the number of rows the P4 server scans per command (p4.maxscanrows). Unset by default, so admin/group policy governs scan limits. Can be overridden by the--max-scan-rowsCLI argument. Must be a non-negative integer when supplied.

- P4MCP_LOG_DIR- Directory for log files. Default:logs/in the server executable's directory. Can be overridden by the--log-dirCLI argument.

- P4MCP_TLS_CA_MODE- TLS certificate source mode.

- system(default): use OS trust store viatruststore.Note:In this mode,truststoreoverrides theverify=parameter — custom CA bundles set viaP4MCP_CA_BUNDLEor--ca-bundleare ignored. To use a custom CA bundle, setP4MCP_TLS_CA_MODE=certifi.
- certifi: disabletruststoreinjection and use default Python TLS certificate behavior. Custom CA bundles (P4MCP_CA_BUNDLE/--ca-bundle) take effect only in this mode.

- OTEL_EXPORTER_OTLP_ENDPOINT- OTLP collector endpoint for telemetry export. Default:https://grpc.public.prd.shared.perforce.com.
- OTEL_EXPORTER_OTLP_PROTOCOL- OTLP export protocol. Onlygrpcis supported; other values fall back togrpcwith a warning.

- If present, uses read-only mode. Safe for exploration and testing.
- If missing, enables write operations. Requires proper permissions on your P4 Server.

- If present, allows anonymous usage statistics collection.
- If missing, disables all usage statistics.

--toolsets- Specify which tool categories to enable.

- Available:files,changelists,shelves,workspaces,jobs,reviews,streams
- Default: All toolsets enabled.
- query_serveris always available regardless of the--toolsetssetting.

--search-transform- Enable search-based tool discovery to reduce token overhead.

- regex— Expose a regex pattern-matching search tool. Best for targeted lookups.
- bm25— Expose a natural-language relevance-ranked search tool. Best for exploratory queries.
- both— Expose both search tools with distinct names (regex_search_tools/regex_call_toolandsemantic_search_tools/semantic_call_tool).
- If omitted, the full tool catalog is sent to the client (default, backward-compatible).
- When enabled,query_serveris always directly visible to the client.
- Security:Admin permission checks (CheckPermissionMiddleware) and--readonlyfiltering remain fully enforced. Search transforms query the real tool catalog internally, so tools blocked by middleware or excluded by read-only mode are never discoverable or callable through the search interface.

--max-results <N>- Cap on the number of rows the P4 server returns per command (p4.maxresults).

- Default:10000. Set to0to disable the limit (server default in effect).
- Protects against runaway AI-driven queries exhausting local memory or overwhelming the server.
- When a command would exceed this limit the server aborts it with an error — it does not truncate — so keep the value generous.
- Must be a non-negative integer; an invalid value fails fast at startup before any P4 connection is attempted.

Priority order:--max-results>P4MCP_MAX_RESULTS> default (10000).

--max-scan-rows <N>- Cap on the number of rows the P4 server scans per command (p4.maxscanrows).