Perforce MCP Server: AI-Powered Version Control for AI Agents

Discover how to supercharge your Perforce workflow with AI using the MCP Perforce Server. This guide shows you how to integrate Perforce version control with VS Code, Claude, and other AI assistants for seamless, AI-powered development.

Table of Contents

What is MCP Perforce Server?

MCP Perforce Server is an enterprise-grade Model Context Protocol (MCP) server that enables AI assistants like Claude, ChatGPT, and GitHub Copilot to interact with Perforce version control systems directly from your development environment.

Think of it as a bridge between AI and Perforce - allowing you to use natural language commands to perform version control operations without leaving your IDE or chat interface.

The Problem It Solves

Before MCP Perforce Server:

flowchart TD
  D[Developer] --> M1[Types p4 commands manually]
  M1 --> M2[Switches between terminal and IDE]
  M2 --> M3[Remembers complex Perforce syntax]
  M3 --> M4[Manually creates changelists]
  M4 --> M5[Error-prone operations]

With MCP Perforce Server:

flowchart TD
  D[Developer request add files to Perforce] --> A[AI agent understands intent]
  A --> S[MCP Perforce server]
  S --> C[Executes p4 add command]
  C --> R[Returns structured result]
  R --> I[All inside IDE or chat]

Why Use MCP Perforce Server?

Alternative to Manual Operations

Replaces:

• Manual Perforce CLI operations in AI workflows
• Custom Git-to-Perforce bridges for AI assistants
• Unsafe direct P4 command execution
• Complex Perforce API integrations

Perfect For:

• Enterprise teams using Perforce with AI tools
• DevOps automation with Claude or ChatGPT
• VS Code and Cursor IDE users with Perforce
• Secure version control in AI-assisted workflows

Key Features

🔒 Enterprise Security

• Read-only by default - Safe for production environments
• Configurable access controls - Fine-grained permission management
• Delete protection - Prevents accidental file deletions
• Standardized error codes - Predictable error handling

🤖 AI Integration

• Works with Claude, ChatGPT, VS Code, and Cursor
• Natural language version control commands
• Automated workflow execution
• Context-aware operations

⚡ Production Ready

• Non-interactive operations
• Comprehensive error handling
• Structured JSON responses
• Cross-platform support (Windows, macOS, Linux)

🔧 Developer Friendly

• Zero configuration with sensible defaults
• Automatic .p4config detection
• Multi-project support
• TypeScript support with full documentation

What Can It Do?

The MCP Perforce Server provides comprehensive Perforce operations through a standardized interface:

Repository Operations

flowchart TD
  O[Repository operations] --> I[p4.info]
  I --> I2[Get server and client info]
  O --> ST[p4.status]
  ST --> ST2[Get workspace status]
  O --> SY[p4.sync]
  SY --> SY2[Sync files from depot]
  O --> OP[p4.opened]
  OP --> OP2[List opened files]

File Operations

flowchart TD
  O[File operations] --> A[p4.add]
  A --> A2[Add new files to Perforce]
  O --> E[p4.edit]
  E --> E2[Open files for editing]
  O --> D[p4.delete]
  D --> D2[Mark files for deletion protected by default]
  O --> R[p4.revert]
  R --> R2[Revert changes to files]
  O --> DF[p4.diff]
  DF --> DF2[Show file differences]

Changelist Operations

flowchart TD
  O[Changelist operations] --> C1[p4.changelist.create]
  C1 --> C1D[Create new changelist]
  O --> C2[p4.changelist.update]
  C2 --> C2D[Update existing changelist]
  O --> C3[p4.changelist.submit]
  C3 --> C3D[Submit changelist]
  O --> C4[p4.submit]
  C4 --> C4D[Submit default changelist]
  O --> C5[p4.describe]
  C5 --> C5D[Describe changelist details]

Utility Operations

flowchart TD
  O[Utility operations] --> F[p4.filelog]
  F --> F2[View file history]
  O --> CL[p4.clients]
  CL --> CL2[List Perforce workspaces]
  O --> CD[p4.config.detect]
  CD --> CD2[Detect and show configuration]

How It Works

Architecture Overview

flowchart TD
  U[User in VS Code add this file to Perforce] --> A[AI assistant understands intent]
  A --> P[MCP protocol layer]
  P --> S[MCP Perforce server]
  S --> S1[Validate request]
  S --> S2[Check permissions]
  S --> S3[Find .p4config]
  S --> S4[Build command]
  S --> C[Perforce CLI p4]
  C --> PS[Perforce server]
  PS --> J[Structured JSON response]
  J --> A

Configuration Detection

The server automatically discovers Perforce configuration:

flowchart TD
  C1[1 Check for .p4config upward from workspace] --> Q{2 Found .p4config?}
  Q -- Yes --> Y[Use file settings]
  Q -- No --> N[Use environment variables]
  Y --> M[3 Merge with MCP environment]
  N --> M
  M --> B[4 Build complete config P4PORT P4USER P4CLIENT]
  B --> V[5 Validate required fields]

Installation and Setup

Step 1: Install the Server

# Install globally via npm
npm install -g mcp-perforce-server

# Verify installation
mcp-perforce-server --help

Step 2: Configure Perforce

Option A: Using .p4config file (Recommended)

Create a .p4config file in your project root:

P4PORT=perforce-server:1666
P4USER=your-username
P4CLIENT=your-workspace-name
P4CHARSET=utf8

Option B: Using environment variables

Set system environment variables:

export P4PORT=perforce-server:1666
export P4USER=your-username
export P4CLIENT=your-workspace-name

Step 3: Prerequisites

Ensure Perforce CLI is installed:

# Test Perforce CLI
p4 -V

# Should output Perforce version information

Using with VS Code

Setting Up with Claude Dev/Cline Extension

1. Install the Claude Dev or Cline extension in VS Code

2. Configure MCP Server

Open your MCP configuration file and add:

{
  "mcpServers": {
    "perforce": {
      "command": "mcp-perforce-server",
      "args": [],
      "env": {
        "P4_READONLY_MODE": "false",
        "P4_DISABLE_DELETE": "true",
        "LOG_LEVEL": "error"
      },
      "alwaysAllow": ["p4.*"],
      "disabled": false
    }
  }
}

Configuration explained:

• "command": "mcp-perforce-server" - The globally installed command
• "P4_READONLY_MODE": "false" - Enable write operations
• "P4_DISABLE_DELETE": "true" - Keep delete protection enabled
• "LOG_LEVEL": "error" - Minimize console noise
• "alwaysAllow": ["p4.*"] - Auto-approve all p4 commands (no prompts)
• "disabled": false" - Ensure server is active

Using with Cursor IDE

Cursor has slightly different MCP configuration:

{
  "mcp": {
    "servers": {
      "perforce": {
        "command": "mcp-perforce-server",
        "args": [],
        "env": {
          "P4_READONLY_MODE": "false",
          "P4_DISABLE_DELETE": "true",
          "LOG_LEVEL": "error"
        },
        "alwaysAllow": true
      }
    }
  }
}

Example Workflows in VS Code

Workflow 1: Adding Files

Natural language command:

User: "Add all new TypeScript files in the src directory to Perforce"

AI Assistant: 
- Discovers new .ts files in src/
- Calls p4.add with file list
- Creates or updates changelist
- Returns confirmation

Behind the scenes:

{
  "tool": "p4.add",
  "arguments": {
    "files": ["src/new-file.ts", "src/another.ts"],
    "changelist": "default"
  }
}

Workflow 2: Creating and Submitting Changes

Natural language:

User: "Create a changelist for my API changes and submit it"

AI Assistant:
1. Gets list of opened files (p4.opened)
2. Creates new changelist (p4.changelist.create)
3. Moves files to changelist
4. Submits changelist (p4.changelist.submit)
5. Reports success

Workflow 3: Checking Status

Natural language:

User: "What files do I have checked out?"

AI Assistant:
- Calls p4.opened
- Formats the list
- Shows file status and changelist info

Silent Operation

For a seamless experience without approval prompts:

Key Settings:

{
  "alwaysAllow": ["p4.*"],     // Auto-approve p4 commands
  "LOG_LEVEL": "error"          // Minimize output
}

This ensures:

• ✅ No approval popups for each command
• ✅ Clean console (errors only)
• ✅ Background execution
• ✅ Fast, uninterrupted workflow

Security and Safety

Default Security Posture

The MCP Perforce Server is secure by default:

flowchart TD
  S[Security levels] --> L1[Maximum safety default]
  L1 --> L1A[P4_READONLY_MODE true]
  L1 --> L1B[P4_DISABLE_DELETE true]
  L1 --> L1C[All write operations blocked]

  S --> L2[Recommended production]
  L2 --> L2A[P4_READONLY_MODE false]
  L2 --> L2B[P4_DISABLE_DELETE true]
  L2 --> L2C[Write enabled delete protected]

  S --> L3[Full access use with caution]
  L3 --> L3A[P4_READONLY_MODE false]
  L3 --> L3B[P4_DISABLE_DELETE false]
  L3 --> L3C[All operations enabled]

Environment Variables

Control server behavior with these variables:

Error Handling

Standardized error codes for reliable error handling:

{
  "ok": false,
  "error": {
    "code": "P4_READONLY_MODE",
    "message": "Server is in read-only mode",
    "details": {...}
  }
}

Common Error Codes:

• P4_NOT_FOUND - Perforce executable not found
• P4_AUTH_FAILED - Authentication failure
• P4_CLIENT_UNKNOWN - Unknown workspace
• P4_CONNECTION_FAILED - Server connection failed
• P4_READONLY_MODE - Operation blocked by read-only mode
• P4_DELETE_DISABLED - Delete operation blocked
• P4_INVALID_ARGS - Invalid parameters

Available Operations

Complete Operation Reference

Repository Information

p4.info - Get server and client information

{
  "tool": "p4.info",
  "arguments": {
    "workspacePath": "/path/to/workspace"
  }
}

p4.status - Get workspace status

{
  "tool": "p4.status",
  "arguments": {
    "workspacePath": "/path/to/workspace"
  }
}

File Management

p4.add - Add files to Perforce

{
  "tool": "p4.add",
  "arguments": {
    "files": ["file1.ts", "file2.ts"],
    "changelist": "default"
  }
}

p4.edit - Open files for edit

{
  "tool": "p4.edit",
  "arguments": {
    "files": ["existing-file.ts"],
    "changelist": "default"
  }
}

p4.revert - Revert changes

{
  "tool": "p4.revert",
  "arguments": {
    "files": ["file.ts"],
    "unchangedOnly": false
  }
}

Changelist Management

p4.changelist.create - Create new changelist

{
  "tool": "p4.changelist.create",
  "arguments": {
    "description": "Fix bug in authentication",
    "files": ["auth.ts", "login.ts"]
  }
}

p4.changelist.submit - Submit changelist

{
  "tool": "p4.changelist.submit",
  "arguments": {
    "changelist": "12345"
  }
}

History and Analysis

p4.filelog - Show file history

{
  "tool": "p4.filelog",
  "arguments": {
    "filespec": "//depot/project/src/...",
    "maxRevisions": 10
  }
}

p4.diff - Show differences

{
  "tool": "p4.diff",
  "arguments": {
    "files": ["modified-file.ts"],
    "summary": false
  }
}

Real-World Use Cases

Use Case 1: Automated Code Review Preparation

Scenario: Developer finishes a feature and needs to submit for review

flowchart TD
  U[User finished authentication feature] --> W1[1 Check workspace status p4.status]
  W1 --> W2[2 Identify modified files]
  W2 --> W3[3 Create changelist p4.changelist.create]
  W3 --> W4[Description add user authentication feature]
  W4 --> W5[4 Add files to changelist]
  W5 --> W6[5 Show diff summary p4.diff]
  W6 --> W7[6 Report changelist number for review]

Use Case 2: Workspace Cleanup

Scenario: Developer wants to clean up their workspace

flowchart TD
  U[User asks to revert unchanged files] --> W1[1 Get opened files p4.opened]
  W1 --> W2[2 Revert unchanged p4.revert unchangedOnly]
  W2 --> W3[3 Get updated opened files list]
  W3 --> W4[4 Present summary to user]

Use Case 3: File History Investigation

Scenario: Developer needs to understand file changes

flowchart TD
  U[User asks who modified module and why] --> W1[1 Get file history p4.filelog]
  W1 --> W2[2 Parse changelist descriptions]
  W2 --> W3[3 Get changelist details p4.describe]
  W3 --> W4[4 Present formatted history]

Use Case 4: Bulk Operations

Scenario: Refactoring across multiple files

flowchart TD
  U[User renamed Auth to Authentication] --> W1[1 Scan modified TypeScript files]
  W1 --> W2[2 Open files for edit p4.edit]
  W2 --> W3[3 Create changelist p4.changelist.create]
  W3 --> W4[Description rename Auth to Authentication]
  W4 --> W5[4 Move files to changelist]
  W5 --> W6[5 Confirm completion]

Troubleshooting

Common Issues and Solutions

Issue 1: Command Approval Prompts

Problem: VS Code asks for approval on every command

Solution:

{
  "alwaysAllow": ["p4.*"]  // Add this to your MCP config
}

Issue 2: Configuration Not Found

Problem: Server can’t find Perforce configuration

Solution:

# Run config detection tool
# The server will show where it's looking

# Or use direct environment variables in MCP config:
{
  "env": {
    "P4PORT": "your-server:1666",
    "P4USER": "your-username",
    "P4CLIENT": "your-workspace"
  }
}

Issue 3: Read-only Mode Errors

Problem: All write operations fail

Solution:

{
  "env": {
    "P4_READONLY_MODE": "false"  // Must be string "false"
  }
}

Issue 4: Too Much Console Output

Problem: Terminal shows every operation

Solution:

{
  "env": {
    "LOG_LEVEL": "error"  // Only show errors
  }
}

Issue 5: Authentication Failures

Problem: p4 login required

Solution:

# Log in via terminal first
p4 login

# Or set up ticket-based authentication
# The server will use your existing p4 tickets

Debug Mode

Enable detailed logging for troubleshooting:

{
  "env": {
    "LOG_LEVEL": "debug"
  }
}

This will show:

• Configuration detection process
• Every p4 command executed
• Full command output
• Error details

Conclusion

The MCP Perforce Server transforms how developers interact with Perforce version control, bringing the power of AI-assisted workflows to enterprise environments.

Key Takeaways

1. Seamless Integration

• Works naturally with VS Code, Cursor, and AI assistants
• No context switching between tools
• Natural language version control commands

2. Enterprise Ready

• Security-first design with safe defaults
• Comprehensive error handling
• Production-tested reliability

3. Developer Friendly

• Zero configuration for basic use
• Automatic workspace detection
• Extensive documentation and examples

4. Open Source

• MIT licensed
• Community-driven development
• Free to use and modify

Getting Started Checklist

• Install mcp-perforce-server globally
• Verify p4 CLI is available
• Create .p4config in your project
• Configure MCP in VS Code/Cursor
• Test with simple commands (p4.info, p4.status)
• Enable write mode when ready (P4_READONLY_MODE=false)
• Set alwaysAllow for silent operation

Resources

• GitHub Repository: github.com/iPraBhu/mcp-perforce-server
• npm Package: npmjs.com/package/mcp-perforce-server
• Configuration Examples: See MCP_CONFIG_EXAMPLES.md in the repository
• Support: Open issues on GitHub or contact @iPraBhu

What’s Next?

The MCP Perforce Server is actively maintained and open to contributions:

Planned Features:

• Additional Perforce operations
• Enhanced changelist management
• Workspace templates
• Integration examples for more IDEs

Want to Contribute?

• ⭐ Star the repository
• 🐛 Report bugs or request features
• 🔧 Submit pull requests
• 📖 Improve documentation

Support the Project

This tool was created by Pratik Bhuite to solve real Perforce automation challenges. If you find it useful:

• ⭐ Star the repository on GitHub
• ☕ Buy me a coffee on Ko-fi
• 📢 Share with your team
• 🤝 Contribute to development

Ready to supercharge your Perforce workflow with AI? Install the MCP Perforce Server today and experience the future of version control!

npm install -g mcp-perforce-server