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

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:

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.

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.

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