Perforce Server

npm version License: MIT Node.js Version TypeScript MCPAmpel

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

1. Install the Perforce CLI and ensure p4 is on PATH.
2. Configure Perforce credentials in .p4config or via MCP env.
3. Add the server to your MCP client.
4. 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:

• PERFORCE_SETUP.md
• MCP_CONFIG_EXAMPLES.md

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