mcp-perforce-server Server

mcp-perforce-server is a Model Context Protocol server for Perforce (p4) with safe defaults, structured JSON responses, and both native-style and MCP-optimized workflows.

GitHub

Documentation

MCP Perforce Server

mcp-perforce-server is a Model Context Protocol server for Perforce (p4) with safe defaults, structured JSON responses, and both native-style and MCP-optimized workflows.

It is designed for AI assistants and IDE integrations that need Perforce access without relying on brittle shell scripting.

What It Provides

59 MCP tools across repository inspection, file operations, changelists, reviews, jobs, labels, streams, analytics, and compliance.
Dual transport support: stdio (IDE/CLI) and SSE (HTTP server for web clients).
Safe-by-default runtime behavior:
- P4_READONLY_MODE=true
- P4_DISABLE_DELETE=true
Batch-capable inputs for the tool surface where native p4 supports multi-target usage.
MCP-specific composite helpers that reduce round trips for common review and search workflows.
Structured responses with ok, result, optional error, optional warnings, and configUsed.
MCP clients see underscore-safe tool names, for example p4_changes.
Incoming calls also accept the historical dotted names, for example p4.changes.

Highlighted Workflows

The server includes higher-level helpers on top of raw p4 commands.

p4.review.bundle: pending review changelists with optional details and reviewers
p4.change.inspect: describe + fixes + reviews + optional diff + optional file history
p4.path.synccheck: drift and sync-state analysis between two depot paths
p4.file.inspect: per-file metadata, history, optional content, and optional blame
p4.workspace.snapshot: workspace info, status, optional config, opened files, and recent changes
p4.search.inspect: grouped search results with optional file metadata and content previews
p4.review.prepare: explicit or discovered changelists prepared into review-ready bundles

Install

npm install -g mcp-perforce-server

Requirements:

Node.js 18+
Perforce CLI available as p4 or p4.exe
Valid Perforce environment via .p4config or MCP env

Quick Start

Install the Perforce CLI and ensure p4 is on PATH.
Configure Perforce credentials in .p4config or via MCP env.
Add the server to your MCP client.
Start in the default safe profile before enabling any write-capable tools.

Example .p4config:

P4PORT=ssl:perforce.example.com:1666
P4USER=your-username
P4CLIENT=your-workspace-name
P4PASSWD=your-password-or-ticket

Example MCP config using the globally installed server:

{
  "mcpServers": {
    "perforce": {
      "command": "mcp-perforce-server"
    }
  }
}

Example MCP config with explicit credentials:

{
  "mcpServers": {
    "perforce": {
      "command": "mcp-perforce-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your-username",
        "P4CLIENT": "your-workspace-name",
        "P4PASSWD": "your-password-or-ticket",
        "P4_READONLY_MODE": "true",
        "P4_DISABLE_DELETE": "true"
      }
    }
  }
}

Windows local-repo example:

{
  "mcpServers": {
    "perforce": {
      "command": "node",
      "args": ["C:\\Tools\\git-projects\\mcp-perforce-server\\dist\\server.js"]
    }
  }
}

Transport Modes

The server supports two transport modes:

Stdio Transport (Default)

Standard input/output transport for IDE and CLI integration. Each MCP client spawns its own server process.

Best for:

VS Code, Cursor, Claude Desktop integration
CLI tools and local automation
Single-user workflows
Process-isolated security model

# Default mode (no flag needed)
mcp-perforce-server

SSE Transport (HTTP Server)

Server-Sent Events transport runs an HTTP server for web-based clients.

Best for:

Web dashboards and analytics UIs
Team collaboration tools
Centralized deployments
Multi-user environments
API integrations

# Start SSE server
mcp-perforce-server --transport=sse

# With custom configuration
MCP_SSE_PORT=8080 MCP_SSE_ENABLE_AUTH=true mcp-perforce-server --transport=sse

SSE Configuration:

Variable	Default	Description
`MCP_SSE_PORT`	`3000`	HTTP server port
`MCP_SSE_HOST`	`0.0.0.0`	Server bind address
`MCP_SSE_PATH`	`/mcp`	SSE endpoint path
`MCP_SSE_CORS_ORIGIN`	`*`	CORS allowed origins
`MCP_SSE_ENABLE_AUTH`	`false`	Enable token authentication
`MCP_SSE_AUTH_TOKEN`	(empty)	Bearer token for auth

SSE Endpoints:

Main: GET http://localhost:3000/mcp
Health: GET http://localhost:3000/health
Post: POST http://localhost:3000/mcp

Production SSE Example:

export MCP_SSE_ENABLE_AUTH=true
export MCP_SSE_AUTH_TOKEN="your-secret-token"
export MCP_SSE_CORS_ORIGIN="https://your-dashboard.com"
export P4_READONLY_MODE=true
mcp-perforce-server --transport=sse

📘 For complete SSE deployment guide, see SSE_SETUP_GUIDE.md

Quick references:

MCP Configuration Examples - Quick config snippets
SSE Setup Guide - Comprehensive deployment guide with Docker, Kubernetes, and production examples

Safety Model

The default runtime profile is conservative.

Setting	Default	Effect
`P4_READONLY_MODE`	`true`	Blocks write-capable tools.
`P4_DISABLE_DELETE`	`true`	Blocks `p4.delete` even when write mode is enabled.

Write-capable tools include:

p4.add, p4.edit, p4.delete, p4.revert, p4.sync
p4.changelist.create, p4.changelist.update, p4.changelist.submit, p4.submit
p4.resolve, p4.shelve, p4.unshelve
p4.copy, p4.move, p4.integrate, p4.merge

Tool Surface

Major categories:

Repository and workspace inspection
File operations and diffing
Changelists and submissions
Merge, shelving, and resolve flows
Search and discovery
Review and workflow composites
Users, clients, streams, labels, jobs, and fixes
Compliance, audit, and operational diagnostics

Notable native parity improvements:

Batch-style inputs for commands such as sync, opened, filelog, annotate, grep, files, dirs, print, fstat, sizes, have, users, streams, jobs, and fixes
Expanded native flag coverage for tools such as sync, interchanges, fstat, files, dirs, streams, clients, labels, jobs, and sizes
Support for both workspace-facing and depot-to-depot diffing via p4.diff and p4.diff2

Configuration

Most installations only need a small set of variables.

Variable	Default	Purpose
`P4_READONLY_MODE`	`true`	Keep the server read-only by default.
`P4_DISABLE_DELETE`	`true`	Prevent delete operations unless explicitly enabled.
`P4CONFIG`	`.p4config`	Config file name used during upward discovery.
`P4_PATH`	`p4` / `p4.exe`	Custom path to the Perforce CLI.
`P4_PERFORMANCE_MODE`	`fast`	Preset: `fast`, `balanced`, `secure`.
`P4_WORKFLOW_CONCURRENCY`	`6`	Max concurrent subcalls for composite tools.
`P4_RESPONSE_CACHE`	`true`	Enable read-response caching.
`P4_RESPONSE_CACHE_TTL_MAP`	unset	Per-tool cache TTL overrides.
`LOG_LEVEL`	`warn`	Server log level.

Perforce connection variables:

P4PORT
P4USER
P4CLIENT
P4PASSWD
P4CHARSET
P4COMMANDCHARSET
P4LANGUAGE

For full configuration tables and examples, see:

Development

npm install
npm run build
npm test
npm run test:integration

Current verification baseline:

npm run build
npm test
npm run test:integration

Documentation

SSE Transport Setup: SSE_SETUP_GUIDE.md - Complete guide for HTTP/web deployments
Tool catalog and descriptions: AGENTS.md
Docs index: docs/README.md
Perforce setup: PERFORCE_SETUP.md
MCP client config examples: MCP_CONFIG_EXAMPLES.md
Publishing workflow: PUBLISHING.md
Release notes draft: RELEASE_NOTES.md

License

MIT