If you have uv installed, you can run P4 MCP Server directly without any manual installation:

# Run the server
uvx p4mcp-server

# Check version
uvx p4mcp-server --version

# Run with arguments
uvx p4mcp-server --readonly --allow-usage

This automatically fetches and runs the latest version from PyPI. No Python virtual environment setup or dependency management needed.

Requirements:

• uv installed on your system
• Python 3.11+ (uv will handle this automatically)

Download the appropriate binary for your operating system:

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

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

# macOS / Linux
unzip p4-mcp-server-mac.zip   # or p4-mcp-server-linux.zip
./p4-mcp-server --help

# Windows
Expand-Archive p4-mcp-server-win.zip -DestinationPath .
.\p4-mcp-server.exe --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 & Linux: p4-mcp-server-<version>.tgz
• Windows: p4-mcp-server-<version>.zip

Run the P4 MCP Server directly on your machine using the default STDIO transport.

Add the following to your mcp.json:

{
  "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"
      ]
    }
  }
}

Note: This example shows explicit env values. If P4CONFIG is set, you can omit them and use the generic configuration example in the MCP client configuration section instead.

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

Pull the Docker image

docker pull ghcr.io/perforce/p4mcp-server:latest

cd /path/to/p4mcp-server
docker build -t ghcr.io/perforce/p4mcp-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",
                "ghcr.io/perforce/p4mcp-server:latest"
            ]
        }
    }
}

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",
                "ghcr.io/perforce/p4mcp-server:latest"
            ]
        }
    }
}

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.

Run the MCP server on a VM using the HTTP transport, allowing clients to connect over the network.

Start the server on the VM:

P4PORT=ssl:perforce.example.com:1666 P4USER=your_username P4PASSWD=YOUR_TICKET ./p4-mcp-server --readonly --transport http --port 8000

Configure the MCP client:

Add the following to your mcp.json:

{
    "servers": {
        "perforce-p4-mcp": {
            "type": "http",
            "url": "http://<ip-or-hostname>:8000/mcp"
        }
    }
}

Note: Ensure the VM's firewall allows inbound connections on the chosen port. For production use, consider placing the server behind a reverse proxy with TLS.

Run the MCP server in a Docker container using HTTP transport and expose the MCP endpoint over a host port.

Start the container:

docker run --rm -p 8000:8000 \
  -e P4PORT=ssl:perforce.example.com:1666 \
  -e P4USER=your_username \
  -e P4PASSWD=YOUR_TICKET \
  ghcr.io/perforce/p4mcp-server:latest \
  python3 -m p4mcp.main --readonly --transport http --port 8000

Configure the MCP client:

Add the following to your mcp.json:

{
  "servers": {
    "perforce-p4-mcp": {
      "type": "http",
      "url": "http://<ip-or-hostname>:8000/mcp"
    }
  }
}

Note: Docker supports HTTP-based deployment as well. The container image defaults to STDIO transport, so the HTTP startup command must explicitly override the default command. If you need write operations, also mount the client root and ticket file paths into the container.

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

See the Claude Code MCP docs for more information.

Using uvx (no installation required):

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

Using pre-built binary:

{
  "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.

{
  "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, P4's property resolution determines which value wins.

The highest sequence number (-s) wins. At equal sequence numbers, the alphabetically-first group name wins.

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 wins because -s2 is higher than -s1.

To block a specific user regardless of group membership:

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

At the same sequence number, user-level properties override group-level and global settings (P4's scope tiebreaker).

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

Note: A group property at a higher -s value can override a user property at a lower sequence number. To ensure a user-level property always wins, give it a high -s value or ensure no group properties use a higher sequence.

Restrict which toolsets are available server-wide using mcp.toolsets.allowed. Only listed toolsets will be enabled; all others are blocked.

Available toolsets: server, changelists, files, jobs, reviews, shelves, workspaces, streams

Allow only changelists and files:

p4 property -a -n mcp.toolsets.allowed -v changelists,files

Remove the allowlist to restore all toolsets:

p4 property -d -n mcp.toolsets.allowed

Disable all write operations (modify tools) while keeping read operations (query tools) available:

p4 property -a -n mcp.toolsets.write -v false

Re-enable writes:

p4 property -a -n mcp.toolsets.write -v true

When write=false, all modify_* tools are blocked but all query_* tools continue to work.

Enable or disable individual toolsets for a specific group.

Disable a toolset for a specific group:

p4 property -a -n mcp.toolset.changelists.enabled -v false -g reviewers

Users in reviewers are blocked from changelists. Users in other groups (with no explicit setting) retain default access.

To restrict a toolset to only one group, disable it for every other group that should not have access:

p4 property -a -n mcp.toolset.files.enabled -v false -g reviewers
p4 property -a -n mcp.toolset.files.enabled -v false -g interns
# Only groups without an explicit "false" retain default access to files

Note: All toolsets are enabled by default. Setting enabled=true for a group is redundant unless you are explicitly overriding a previous false setting. At the same sequence number, a group property overrides a global property (P4's scope tiebreaker), so a group enabled=true can override a global enabled=false. To ensure a global setting cannot be overridden, give it a high -s value. To isolate a toolset to specific groups, disable it for the groups you want to block.

Control write access for each toolset at the group level.

Disable writes for a specific toolset per group:

p4 property -a -n mcp.toolset.workspaces.write -v false -g reviewers

This blocks modify_workspaces for the group while query_workspaces remains accessible.

Restrict a group to specific tools within a toolset using mcp.toolset.<name>.tools.

Allow only query_files (block modify_files) for developers:

p4 property -a -n mcp.toolset.files.tools -v query_files -g developers

Allow both query and modify for leads:

p4 property -a -n mcp.toolset.reviews.tools -v query_reviews,modify_reviews -g leads

Tool-specific overrides can restrict access even when writes are enabled:

p4 property -a -n mcp.toolsets.write -v true
p4 property -a -n mcp.toolset.files.tools -v query_files -g developers
# Result: modify_files is BLOCKED — tool list restricts

Note: Tool-specific overrides cannot bypass write restrictions. The server checks write permissions before evaluating tool lists. If write=false is set at any level, write tools are blocked regardless of the tool list.

When a user belongs to multiple groups with conflicting settings, P4 resolves each property to a single value. The MCP server does not perform its own multi-group logic — it uses whichever value P4 returns.

P4's resolution rules for a given property name:

1. Highest -s (sequence number) wins. This is the primary sort key.
2. At the same sequence number: user scope > group scope > global scope.
3. Between groups at the same sequence: the alphabetically-first group name wins.

P4 does not compare values. It picks the winning entry by position, not by content.

Example — groups at the same sequence (default):

p4 property -a -n mcp.toolset.files.enabled -v true -g developers
p4 property -a -n mcp.toolset.files.enabled -v false -g leads
# User in both groups → resolved value is "true"
# Reason: "developers" < "leads" alphabetically, so developers wins

Swapping the values would give false — developers still wins regardless of the value.

Example — only one group has a setting:

p4 property -a -n mcp.toolset.files.enabled -v false -g leads
# developers has no setting
# User in developers + leads → resolved value is "false"
# Reason: leads is the only group with a value, so it wins

Example — write access:

p4 property -a -n mcp.toolset.files.write -v false -g developers
p4 property -a -n mcp.toolset.files.write -v true -g leads
# User in both groups → resolved value is "false"
# Reason: "developers" < "leads" alphabetically, not because false is "more restrictive"

Example — tool lists (no union):

p4 property -a -n mcp.toolset.reviews.tools -v query_reviews -g developers
p4 property -a -n mcp.toolset.reviews.tools -v query_reviews,modify_reviews -g leads
# User in both groups → resolved value is "query_reviews"
# Reason: "developers" wins alphabetically. P4 returns one value, not a union.

Example — using -s to control which group wins:

p4 property -a -n mcp.enabled -v false -s1 -g noaccessgroup
p4 property -a -n mcp.enabled -v true  -s2 -g accessgroup
# accessgroup wins because -s2 > -s1 (highest sequence wins)

Tip: To get predictable results with multiple groups, always use explicit -s values rather than relying on alphabetical group name ordering.

Disable a single toolset for all users without affecting others:

p4 property -a -n mcp.toolset.reviews.enabled -v false

This blocks both query_reviews and modify_reviews for all users. Other toolsets remain unaffected.

Restrict a specific group to read-only without affecting other groups:

p4 property -a -n mcp.toolsets.write -v false -g problematic_group

Users in other groups retain full write access. If a user belongs to both the restricted group and an unrestricted group, P4's property resolution determines the outcome — typically the alphabetically-first group name wins at equal sequence numbers. Use explicit -s values for predictable results.

• 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
  • search - Search for files by name pattern (wildcard matching)
  • grep - Search for files by content pattern (text search)
• Parameters: file_path, file2 (for diff), pattern (for search/grep), case_insensitive (for grep), max_results, diff2 (boolean)
• Use cases: Code analysis, file comparison, history tracking, blame analysis, file discovery, content search

• 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:
  • list - List streams with optional filters (path pattern, owner, type)
  • get - Get a detailed stream specification
  • children - Get child streams of a given stream
  • parent - Get the parent stream
  • graph - Get the full stream graph (parent + children)
  • integration_status - Get integration status between stream and parent (p4 istat)
  • get_workspace - Get a workspace spec bound to a stream
  • list_workspaces - List workspaces bound to a stream
  • validate_file - Validate file paths against a stream's view
  • validate_submit - Validate opened files for submit in a stream workspace
  • check_resolve - Check for pending stream spec conflicts
  • interchanges - List changelists awaiting integration between streams
• Parameters:
  • stream_name - Stream depot path (required for get, children, parent, graph, check_resolve, interchanges)
  • stream_path - Path pattern(s) for list (e.g., ["//depot/..."])
  • filter - Filter expression for list (e.g., "Owner=alice&Type=development")
  • fields - Fields to return for list (e.g., ["Stream", "Owner", "Type"])
  • workspace - Workspace name for get_workspace, validate_file, validate_submit
  • file_paths - File paths for validate_file
  • view_without_edit - View locked stream spec without opening for edit
  • at_change - Retrieve historical stream spec at a changelist number
  • both_directions - Show integration status in both directions
  • force_refresh - Force istat cache refresh
  • reverse, long_output, limit - Options for interchanges
  • unloaded, all_streams, viewmatch - Filters for list
  • max_results - Maximum results
• Use cases: Stream hierarchy exploration, integration status tracking, workspace validation, view compatibility checks

• Actions - create, update, delete, switch
• Parameters - name, specs (WorkspaceSpec object with View, Root, Options, etc.)
• Requires - Read-only mode disabled, 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, interactive PROCEED/CANCEL elicitation prompt for delete operations with item details
• 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

• Actions:
  • create - Create a new stream (mainline, development, release, task, virtual, etc.)
  • update - Update stream properties (name, description, options, paths, parent_view)
  • delete - Delete a stream
  • edit_spec - Open stream spec for editing (p4 stream edit)
  • resolve_spec - Resolve stream spec conflicts
  • revert_spec - Revert stream spec edits
  • shelve_spec - Shelve stream spec edits to a numbered changelist
  • unshelve_spec - Unshelve stream spec edits
  • copy - Copy changes between parent and child streams
  • merge - Merge changes between parent and child streams
  • integrate - Integrate changes with advanced options
  • populate - Populate a new stream with files (branch)
  • switch - Switch a workspace to a different stream
  • create_workspace - Create a new workspace bound to a stream
• Parameters:
  • stream_name - Stream depot path (required for create, update, delete, edit_spec, resolve_spec, revert_spec, switch)
  • stream_type - Stream type for create: mainline, development, sparsedev, release, sparserel, task, virtual
  • parent - Parent stream for non-mainline create
  • name, description - Stream display name and description
  • options - Stream options: allsubmit/ownersubmit, unlocked/locked, toparent/notoparent, fromparent/nofromparent, mergedown/mergeany
  • parent_view - Parent view treatment: inherit or noinherit
  • paths, remapped, ignored - Stream view mappings
  • changelist - Changelist for spec editing or propagation operations
  • resolve_mode - Resolve mode for resolve_spec: auto, accept_theirs, accept_yours
  • parent_stream - Override parent for propagation (-P flag)
  • branch - Branch spec for integrate/populate (-b flag)
  • file_paths - File paths for propagation
  • preview - Preview only, no changes (-n flag)
  • force - Force operation (-f flag)
  • reverse - Reverse direction (-r flag)
  • max_files - Limit files processed (-m flag)
  • quiet - Suppress informational messages (-q flag)
  • output_base - Show base revision with scheduled resolve (-Ob flag for merge/integrate) or list files created (-o flag for populate)
  • virtual - Copy using virtual stream (-v flag, copy only)
  • schedule_branch_resolve - Schedule branch resolves instead of automatic branching (-Rb flag, integrate only)
  • integrate_around_deleted - Integrate around deleted revisions (-Di flag, integrate only)
  • skip_cherry_picked - Skip cherry-picked revisions already integrated (-Rs flag, integrate only)
  • source_path, target_path - Source and target paths for populate
  • workspace - Workspace name for switch
  • workspace_name, root, host, alt_roots - Workspace creation parameters
• Safety: Stream existence validation, locked stream detection, bound workspace warnings, open file checks for view-affecting changes
• Use cases: Stream creation and management, branch propagation (merge/copy/integrate), spec conflict resolution, workspace provisioning

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:
     bash

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

   • Windows:
     powershell

     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 to the P4 server 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: CERTIFICATE_VERIFY_FAILED errors when using review tools Solutions:

1. System trust store: By default, the server uses the OS trust store via truststore. Ensure your corporate CA is installed in the OS certificate store.
2. Custom CA bundle: To use a custom CA certificate, you must first set P4MCP_TLS_CA_MODE=certifi (to disable truststore), then provide the CA path via --ca-bundle /path/to/ca.pem or P4MCP_CA_BUNDLE. In the default system mode, truststore overrides custom CA bundles and they are silently ignored.
3. Disable verification: Use --ssl-no-verify or set P4MCP_SSL_VERIFY=false (not recommended for production). This works in both TLS modes.

Note: These SSL settings only apply when the Swarm URL uses HTTPS. If Swarm is configured with an http:// URL, SSL verification is not performed and these settings have no effect.

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 a 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.