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
Open 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:
Developer → Types p4 commands manually
→ Switches between terminal and IDE
→ Remembers complex Perforce syntax
→ Manually creates changelists
→ Error-prone manual operationsWith MCP Perforce Server:
Developer → "Add these files to Perforce"
AI Agent → Understands intent
→ Uses MCP Perforce Server
→ Executes p4 add command
→ Returns structured result
→ All from within IDE/chatWhy 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
.p4configdetection - 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
┌─────────────────────────────────────────────┐
│ Repository Operations │
├─────────────────────────────────────────────┤
│ │
│ p4.info │
│ └─ Get server and client information │
│ │
│ p4.status │
│ └─ Get workspace status │
│ │
│ p4.sync │
│ └─ Sync files from depot │
│ │
│ p4.opened │
│ └─ List opened files │
│ │
└─────────────────────────────────────────────┘File Operations
┌─────────────────────────────────────────────┐
│ File Operations │
├─────────────────────────────────────────────┤
│ │
│ p4.add │
│ └─ Add new files to Perforce │
│ │
│ p4.edit │
│ └─ Open files for editing │
│ │
│ p4.delete │
│ └─ Mark files for deletion │
│ (Protected by default) │
│ │
│ p4.revert │
│ └─ Revert changes to files │
│ │
│ p4.diff │
│ └─ Show file differences │
│ │
└─────────────────────────────────────────────┘Changelist Operations
┌─────────────────────────────────────────────┐
│ Changelist Operations │
├─────────────────────────────────────────────┤
│ │
│ p4.changelist.create │
│ └─ Create new changelist │
│ │
│ p4.changelist.update │
│ └─ Update existing changelist │
│ │
│ p4.changelist.submit │
│ └─ Submit changelist │
│ │
│ p4.submit │
│ └─ Submit default changelist │
│ │
│ p4.describe │
│ └─ Describe changelist details │
│ │
└─────────────────────────────────────────────┘Utility Operations
┌─────────────────────────────────────────────┐
│ Utility Operations │
├─────────────────────────────────────────────┤
│ │
│ p4.filelog │
│ └─ View file history │
│ │
│ p4.clients │
│ └─ List Perforce workspaces │
│ │
│ p4.config.detect │
│ └─ Detect and show configuration │
│ │
└─────────────────────────────────────────────┘How It Works
Architecture Overview
┌──────────────────────────────────────────────────────┐
│ MCP Perforce Server Architecture │
├──────────────────────────────────────────────────────┤
│ │
│ User in VS Code │
│ "Add this file to Perforce" │
│ ↓ │
│ ┌─────────────────────────────┐ │
│ │ AI Assistant (Claude/etc) │ │
│ │ Understands intent │ │
│ └─────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────┐ │
│ │ MCP Protocol Layer │ │
│ │ (Standardized interface) │ │
│ └─────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────┐ │
│ │ MCP Perforce Server │ │
│ │ • Validates request │ │
│ │ • Checks permissions │ │
│ │ • Finds .p4config │ │
│ │ • Builds command │ │
│ └─────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────┐ │
│ │ Perforce CLI (p4) │ │
│ │ Executes actual command │ │
│ └─────────────────────────────┘ │
│ ↓ │
│ ┌─────────────────────────────┐ │
│ │ Perforce Server │ │
│ │ Performs operation │ │
│ └─────────────────────────────┘ │
│ ↓ │
│ Structured JSON Response │
│ Back to AI Assistant │
│ │
└──────────────────────────────────────────────────────┘Configuration Detection
The server automatically discovers Perforce configuration:
┌────────────────────────────────────────┐
│ Configuration Discovery │
├────────────────────────────────────────┤
│ │
│ 1. Check for .p4config file │
│ Search upward from workspace │
│ ↓ │
│ 2. Found .p4config? │
│ ├─ Yes: Use file settings │
│ └─ No: Use environment variables │
│ ↓ │
│ 3. Merge with MCP environment │
│ Environment overrides file │
│ ↓ │
│ 4. Build complete configuration │
│ P4PORT, P4USER, P4CLIENT, etc. │
│ ↓ │
│ 5. Validate configuration │
│ Check all 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 --helpStep 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=utf8Option B: Using environment variables
Set system environment variables:
export P4PORT=perforce-server:1666
export P4USER=your-username
export P4CLIENT=your-workspace-nameStep 3: Prerequisites
Ensure Perforce CLI is installed:
# Test Perforce CLI
p4 -V
# Should output Perforce version informationUsing 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 confirmationBehind 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 successWorkflow 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 infoSilent 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:
┌────────────────────────────────────────┐
│ Security Levels │
├────────────────────────────────────────┤
│ │
│ 🔒 Maximum Safety (Default) │
│ ├─ P4_READONLY_MODE=true │
│ ├─ P4_DISABLE_DELETE=true │
│ └─ All write ops blocked │
│ │
│ 🛡️ Recommended (Production) │
│ ├─ P4_READONLY_MODE=false │
│ ├─ P4_DISABLE_DELETE=true │
│ └─ Write enabled, delete protected │
│ │
│ ⚠️ Full Access (Use with Caution) │
│ ├─ P4_READONLY_MODE=false │
│ ├─ P4_DISABLE_DELETE=false │
│ └─ All operations enabled │
│ │
└────────────────────────────────────────┘Environment Variables
Control server behavior with these variables:
| Variable | Description | Default |
|---|---|---|
P4_READONLY_MODE | Enable read-only mode | true |
P4_DISABLE_DELETE | Disable delete operations | true |
P4_PATH | Path to p4 executable | p4 |
P4CONFIG | Config file name | .p4config |
LOG_LEVEL | Logging level (error/warn/info/debug) | warn |
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 foundP4_AUTH_FAILED- Authentication failureP4_CLIENT_UNKNOWN- Unknown workspaceP4_CONNECTION_FAILED- Server connection failedP4_READONLY_MODE- Operation blocked by read-only modeP4_DELETE_DISABLED- Delete operation blockedP4_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
User: "I've finished the user authentication feature.
Create a changelist and prepare it for review."
AI Agent Workflow:
├─ Step 1: Check workspace status (p4.status)
├─ Step 2: Identify modified files
├─ Step 3: Create changelist (p4.changelist.create)
│ └─ Description: "Add user authentication feature"
├─ Step 4: Add files to changelist
├─ Step 5: Show diff summary (p4.diff)
└─ Step 6: Report changelist number for reviewUse Case 2: Workspace Cleanup
Scenario: Developer wants to clean up their workspace
User: "Revert all unchanged files and show me what's still open"
AI Agent Workflow:
├─ Step 1: Get opened files (p4.opened)
├─ Step 2: Revert unchanged (p4.revert with unchangedOnly)
├─ Step 3: Get updated opened files list
└─ Step 4: Present summary to userUse Case 3: File History Investigation
Scenario: Developer needs to understand file changes
User: "Who last modified the authentication module and why?"
AI Agent Workflow:
├─ Step 1: Get file history (p4.filelog)
├─ Step 2: Parse changelist descriptions
├─ Step 3: Get changelist details (p4.describe)
└─ Step 4: Present formatted historyUse Case 4: Bulk Operations
Scenario: Refactoring across multiple files
User: "I renamed the Auth class to Authentication everywhere.
Add all modified TypeScript files to a new changelist."
AI Agent Workflow:
├─ Step 1: Scan for modified .ts files
├─ Step 2: Open files for edit (p4.edit)
├─ Step 3: Create changelist (p4.changelist.create)
│ └─ Description: "Rename Auth to Authentication"
├─ Step 4: Move files to changelist
└─ Step 5: Confirm completionTroubleshooting
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 ticketsDebug 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-serverglobally - Verify
p4CLI is available - Create
.p4configin 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
alwaysAllowfor 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.mdin 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