Download the appropriate binary for your operating system:

• macOS: p4-mcp-server-mac.zip
• Windows: p4-mcp-server-win.zip

Extract and use the executable directly. No Python installation is required.

# Windows
unzip p4-mcp-server-2025.2.0.zip
cd p4-mcp-server-2025.2.0
./p4-mcp-server.exe --help

# macOS
tar -xzf p4-mcp-server-2025.2.0.tgz
cd p4-mcp-server-2025.2.0
./p4-mcp-server --help

Requirements:

• Python 3.11+ (with Tkinter)

Build:

• macOS: chmod +x build.sh && ./build.sh package
• Linux: chmod +x build.sh && ./build.sh package
• Windows: build.bat package

Output:

• macOS: p4-mcp-server-<version>.tgz
• Windows: p4-mcp-server-<version>.zip

Run the P4 MCP Server from a Docker container with STDIO transport, allowing MCP clients to manage the container lifecycle.

Note: Docker-based execution is currently supported on macOS and Linux only.

Prerequisites

• Docker installed and running
• Valid P4 credentials and access to a P4 server

Build the Docker Image

cd /path/to/p4mcp-server
docker build -t p4-mcp-server .

Configure MCP Client

Add the following to your mcp.json:

{
    "servers": {
        "perforce-p4mcp-docker": {
            "command": "docker",
            "args": [
                "run", "-i", "--rm",
                "--hostname", "your-hostname",
                "-e", "P4PORT=ssl:perforce.example.com:1666",
                "-e", "P4USER=your_username",
                "-e", "P4CLIENT=your_workspace",
                "-v", "/Users/your_username/.p4tickets:/home/mcpuser/.p4tickets:ro",
                "p4-mcp-server"
            ]
        }
    }
}

Configuration Options

Authentication

Using P4 tickets:

# macOS/Linux
-v /Users/your_username/.p4tickets:/home/mcpuser/.p4tickets:ro

Note: Use the full path to your tickets file (not ~). After running p4 login, restart the MCP server to pick up the new ticket.

Using a password:

-e P4PASSWD="your_password"

Workspace Host Restrictions

⚠️ Important: Docker containers have their own hostname, which differs from your local machine. If your P4 workspace is restricted to a specific host, operations like sync will fail.

To resolve this, set the container hostname to match your workspace's host restriction:

--hostname your-hostname

To find your workspace host name:

# macOS/Linux
p4 client -o your_workspace | grep "^Host:"

Mounting Client Root for Write Operations

⚠️ Important: By default, the Docker container cannot access your local workspace files. For write operations like sync, submit, or reconcile, you must mount your client root directory into the container at the same path.

Add a volume mount for your client root:

-v /path/to/your/client/root:/path/to/your/client/root

Example configuration with client root mounted:

{
    "servers": {
        "perforce-p4mcp-docker": {
            "command": "docker",
            "args": [
                "run", "-i", "--rm",
                "--hostname", "your-hostname",
                "-e", "P4PORT=ssl:perforce.example.com:1666",
                "-e", "P4USER=your_username",
                "-e", "P4CLIENT=your_workspace",
                "-v", "/Users/your_username/.p4tickets:/home/mcpuser/.p4tickets",
                "-v", "/path/to/client/root:/path/to/client/root",
                "p4-mcp-server"
            ]
        }
    }
}

To find your client root:

p4 client -o your_workspace | grep "^Root:"

Note: The mount path inside the container must match the client root path exactly, as P4 tracks files by their absolute paths.

See the JetBrains AI Assistant VCS Integration documentation for detailed configuration steps.

See the Claude Code MCP docs for more information.

{
  "mcpServers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

See the Cursor MCP documentation for more information.

{
  "mcpServers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

See the Eclipse MCP documentation for more information.

{
  "servers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

See the Kiro MCP documentation for more information.

{
  "mcpServers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

See the VS Code documentation for more information. Add the following to your VS Code MCP settings:

{
  "servers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

See the Windsurf MCP documentation for more information.

{
  "mcpServers": {
    "perforce-p4-mcp": {
      "command": "/absolute/path/to/p4-mcp-server",
      "env": {
        "P4PORT": "ssl:perforce.example.com:1666",
        "P4USER": "your_username",
        "P4CLIENT": "your_workspace"
      },
      "args": [
        "--readonly", "--allow-usage"
      ]
    }
  }
}

To prevent access for all members of a specific group:

p4 property -a -n mcp.enabled -v false -g noaccessgroup

You can set multiple group restrictions the same way.

When a user belongs to multiple groups with conflicting settings, sequence order (-s) determines which settings apply.

Lower sequence numbers are evaluated first.

Example:

p4 property -a -n mcp.enabled -v false -s1 -g noaccessgroup
p4 property -a -n mcp.enabled -v true  -s2 -g accessgroup

In this example, accessgroup overrides noaccessgroup because it is evaluated later.

To block a specific user regardless of group membership:

p4 property -a -n mcp.enabled -v false -u noaccessuser

User-level properties always override group-level settings.

Example: Even if noaccessuser is in accessgroup (where MCP is enabled), the user property takes precedence and MCP is disabled.

• Actions:
  • server_info - Get P4 version, uptime, and configuration
  • current_user - Get current user information and permissions
• Use cases - Server diagnostics, user verification, connection testing

• Actions:
  • list - List all workspaces (optionally filtered by user)
  • get - Get a detailed workspace specification
  • type - Check workspace type and configuration
  • status - Check workspace sync status
• Parameters: workspace_name, user, max_results
• Use cases: Workspace discovery, configuration review, status checking

• Actions:
  • get - Get detailed changelist information (files, description, jobs)
  • list - List changelists with filters (status, user, workspace)
• Parameters: changelist_id, status (pending/submitted), workspace_name, max_results
• Use cases: Code review, history tracking, changelist analysis

• Actions:
  • content - Get file content at a specific revision
  • history - Get file revision history and integration records
  • info - Get file basic details (type, size, permissions)
  • metadata - Get file metadata (attributes, filesize, etc.)
  • diff - Compare file versions (depot-to-depot or mixed)
  • annotations - Get file annotations with blame information
• Parameters: file_path, file2 (for diff), max_results, diff2 (boolean)
• Use cases: Code analysis, file comparison, history tracking, blame analysis

• Actions:
  • list - List shelved changes by user or globally
  • diff - Show differences in shelved files
  • files - List files in a specific shelf
• Parameters: changelist_id, user, max_results
• Use cases: Code review, work-in-progress tracking, collaboration

• Actions:
  • list_jobs - List jobs associated with a changelist
  • get_job - Get detailed job information and status
• Parameters: changelist_id, job_id, max_results
• Use cases: Defect tracking, requirement traceability, project management

• Actions:
  • list - List all reviews with optional filtering
  • dashboard - Get current user's review dashboard (my reviews, needs attention)
  • get - Get detailed review information
  • transitions - Get available state transitions for a review
  • files_readby - Get files read status by users
  • files - Get files in a review (with optional version range)
  • activity - Get review activity history
  • comments - Get comments on a review
• Parameters:
  • review_id - Review ID (required for get, transitions, files_readby, files, comments, activity)
  • review_fields - Comma-separated fields to return (e.g., "id,description,author,state")
  • comments_fields - Fields for comments (default: "id,body,user,time")
  • up_voters - List of up voters for transitions
  • from_version, to_version - Version range for files action
  • max_results - Maximum results (default: 10)
• Use cases: Code review discovery, review status tracking, comment retrieval, review activity monitoring

• Actions - create, update, delete, switch
• Parameters - name, specs (WorkspaceSpec object with View, Root, Options, etc.)
• Requires - Non-read only mode, appropriate permissions
• Use cases - Environment setup, workspace maintenance, branch switching

• Actions - create, update, submit, delete, move_files
• Parameters - changelist_id, description, file_paths
• Safety - Ownership checks, confirmation for destructive operations
• Use cases - Code submission, work organization, file grouping

• Actions - add, edit, delete, move, revert, reconcile, resolve, sync
• Parameters - file_paths, changelist, force, mode (for resolve operations)
• Resolve modes - auto, safe, force, preview, theirs, yours
• Use cases - File editing, conflict resolution, workspace synchronization

• Actions - shelve, unshelve, update, delete, unshelve_to_changelist
• Parameters - changelist_id, file_paths, target_changelist, force
• Use cases - Temporary storage, code sharing, backup before experiments

• Actions - link_job, unlink_job
• Parameters - changelist_id, job_id
• Use cases - Defect tracking integration, requirement linking

• Actions:
  • create - Create a new review from a changelist
  • refresh_projects - Refresh project associations
  • vote - Vote on a review (up, down, clear)
  • transition - Change review state (needsRevision, needsReview, approved, committed, rejected, archived)
  • append_participants - Add reviewers/groups to a review
  • replace_participants - Replace all participants
  • delete_participants - Remove participants from a review
  • add_comment - Add a comment to a review
  • reply_comment - Reply to an existing comment
  • append_change - Add a changelist to an existing review
  • replace_with_change - Replace review content with a changelist
  • join - Join a review as a participant
  • leave - Leave a review
  • archive_inactive - Archive inactive reviews
  • mark_comment_read / mark_comment_unread - Mark individual comment read status
  • mark_all_comments_read / mark_all_comments_unread - Mark all comments read status
  • update_author - Change the review author
  • update_description - Update review description
  • obliterate - Permanently delete a review
• Parameters:
  • review_id - Review ID (required for most actions)
  • change_id - Changelist ID (required for create, append_change, replace_with_change)
  • description - Review description
  • reviewers, required_reviewers - Lists of reviewer usernames
  • reviewer_groups - Reviewer groups with requirements
  • vote_value - Vote value: up, down, clear
  • version - Review version for voting
  • transition - Target state: needsRevision, needsReview, approved, committed, approved:commit, rejected, archived
  • jobs, fix_status, cleanup - Job linking and cleanup options for transitions
  • users, groups - Structured participant data for append/replace/delete
  • body - Comment body text
  • task_state - Comment task state: open, comment
  • notify - Notification mode: immediate, delayed
  • comment_id - Comment ID for replies or marking read/unread
  • context - Comment context (file, line numbers, content, version)
  • not_updated_since, max_reviews - Filters for archive_inactive
  • new_author, new_description - Values for update actions
• Use cases: Code review workflow, review state management, collaborative commenting, participant management, review cleanup

• Parameters - operation_id, source_tool, user_confirmed
• Safety - Requires explicit user confirmation, logs all operations
• Supported Resources - Changelists, workspaces, shelves
• Use cases - Cleanup operations, resource management

Symptoms: OS cannot find or execute the binary; error includes ENOENT or "No such file or directory".
Solutions:

1. Check the path: Make sure the command field uses the correct absolute path for your OS:
   • macOS/Linux: /absolute/path/to/p4-mcp-server
   • Windows: C:\absolute\path\to\p4-mcp-server.exe
2. Ensure the binary exists and is executable:
   • macOS/Linux:

     ls -l /absolute/path/to/p4-mcp-server && chmod +x /absolute/path/to/p4-mcp-server
     

   • Windows:

     dir C:\absolute\path\to\p4-mcp-server.exe
     

3. On Windows, ensure the binary is not blocked:
   • Right-click the .exe file, select Properties, and if present, click Unblock.

Symptoms: Cannot connect to P4 Server
Solutions:

1. Verify the P4PORT environment variable: echo $P4PORT (macOS) or echo $env:P4PORT (Windows)
2. Test the direct connection: p4 info
3. Check server availability: ping perforce.example.com
4. Verify the port and protocol (ssl: prefix for SSL connections).

Symptoms: SSL trust errors when connecting
Solutions:

1. Trust the server: p4 trust -f -y
2. Check trust status: p4 trust -l
3. For persistent issues, verify the SSL configuration.

Symptoms: Authentication failures
Solutions:

1. Log in to P4: p4 login -a
2. Check login status: p4 login -s
3. Verify the user exists: p4 users -m 1 your_username
4. For persistent issues, check password or use ticket-based authentication.

Symptoms: Login failures
Solutions:

1. Reset the password through P4 administrator.
2. Use ticket-based authentication: p4 login -a
3. Verify the username is correct: p4 info

Symptoms: Workspace not found errors
Solutions:

1. List the available workspaces: p4 clients
2. Verify the P4CLIENT environment variable.
3. Create a workspace if needed: p4 client workspace_name
4. Check the workspace ownership: p4 client -o workspace_name

Symptoms: Files are outside the workspace mapping
Solutions:

1. Check the client view: p4 client -o workspace_name
2. Update the workspace mapping to include the required paths.
3. Use p4 where file_path to check the mapping.

Symptoms: Insufficient permissions for operations
Solutions:

1. Check the file ownership: p4 opened file_path
2. Verify the user permissions: p4 protects file_path
3. Ensure proper group membership.
4. For admin operations, verify admin permissions.

Symptoms: Exclusive lock conflicts
Solutions:

1. Check who has the file open: p4 opened file_path
2. Contact the user to resolve conflicts.
3. Admin can force operations if necessary.

Symptoms: Long response times
Solutions:

1. Use the max_results parameter to limit the query size.
2. Use specific file paths instead of wildcards.
3. Check network connectivity to P4.
4. Monitor server performance.

Symptoms: High memory usage
Solutions:

1. Reduce max_results for large queries.
2. Process files in batches.
3. Restart the MCP server periodically for long-running sessions.

Symptoms: Conflict with built-in or other MCP tools
Solutions:

1. Disable any built-in or conflicting MCP server tools in your environment or configuration.
2. Ensure the P4 MCP server tools are properly registered and enabled.
3. Restart the MCP server after applying configuration changes to load the correct tools.

Symptoms: Invalid context or outdated session history
Solutions:

1. Provide a P4-related context when writing prompts.
2. Start a new session if the existing session is old or contains conflicting prompt history.