query_changelists
Get changelist details and list changelists (READ permission)
LABSCO SUMMARY
Depot questions answered without syncing a workspace.
Each tool carries the READ permission marker and dispatches on an action, so who changed this file and what the review said is two calls rather than a p4 session plus a browser. The stream tools reach past file history into parent and child graphs, integration status and interchanges — the answers that decide whether a merge is safe to start.
What it is
Eight read-only query tools over a Perforce server, each dispatching on an action parameter: server, workspaces, files, changelists, shelves, jobs, reviews and streams.
What you get
- File work: content, history, info, a diff between two revisions, annotations, search by name and grep by content
- Changelists listed and read in detail, filtered by user, workspace, depot path or status
- Shelved work listed, with its diff and its file list
- Workspaces listed and checked for type and status, plus server and current-user information
- Jobs read from a changelist or fetched by job ID
- Reviews listed and read, filtered by state, project, keywords, version range and up-voters, with transitions included on request
- Streams queried for spec, parent, children and graph, integration status, interchanges, resolve state and file validation
Requirements
A Perforce server and workspace you can reach — P4PORT, P4USER and P4CLIENT — plus uv on your PATH, which resolves the Python runtime through UV_PYTHON. Every tool is marked READ permission.
Setup effort
One command plus credentials — uvx p4mcp-server --readonly --allow-usage, then supply credentials
USE CASES
01
Finding out who last touched a file and why
Annotate the file to see which revision each line came from, then read the changelist behind it for the description and the rest of the files it moved.
02
Reading a review before you weigh in on it
Pull the review with its state and comments, filtered by project or keyword, and check the jobs attached to the changelist so the review is read against what it was meant to fix.
03
Judging whether a merge between streams is safe
Ask the stream for its parent and child graph, integration status and interchanges — the changes waiting to move — then read the changelists those interchanges name.
04
Seeing what a colleague has shelved
List their shelves, read the diff of the shelved changelist, and check which workspace it came from before you decide to unshelve it.
05
Grepping the depot for a string you cannot find locally
Search by file name or grep by content, case-insensitively and capped by max_results, across paths your workspace never synced.
8 tools
Counted once with only startup setup. Other versions, modes or optional credentials may expose a different list.
query_files
Get file content, history, info, diff, annotations, search by name, grep by content (READ permission)
query_jobs
Get jobs from changelist and get job details (READ permission)
query_reviews
Get review details and list reviews (READ permission). Open review - state is 'approved but pending=true' or 'needsReview' or 'needsRevision'. Closed review - state is 'approved but pending=false' or 'rejected' or 'archived'.
query_server
Get server info and current user information (READ permission)
query_shelves
List shelves, get shelve diff and files (READ permission)
query_streams
Query streams: list, get spec, children/parent/graph, integration status, workspaces, validate files, check resolve, interchanges (READ permission)
query_workspaces
Get workspace details, list workspaces, check type and status (READ permission)
BEFORE YOU INSTALL
What to know first
Tools you get
8 tools when we connected; the project documents 15. 8 is the read-only set; without --readonly the 7 modify_* tools register too. --toolsets and server-side administrator settings can narrow the set, and --search-transform replaces it with search tools.
Requires
- Connection to a P4 Server with proper credentials
- Valid P4 login (ticket-based or password)
- P4USER in your environment
Where it runs
All 6 documented clients run the server on your machine.
INSTALLATION
Connect your client
Server setup
TERMINAL
uvx p4mcp-server --readonly --allow-usageMCP Clients
Claude Code, Cursor, Kiro, Windsurf
JSON
{
"mcpServers": {
"perforce-p4-mcp": {
"command": "uvx",
"args": [
"p4mcp-server",
"--readonly",
"--allow-usage"
],
"env": {
"P4PORT": "ssl:<YOUR_PERFORCE_HOST>:1666",
"P4USER": "<YOUR_P4USER>",
"P4CLIENT": "<YOUR_P4CLIENT>"
}
}
}
}Eclipse, VS Code
JSON
{
"servers": {
"perforce-p4-mcp": {
"command": "uvx",
"args": [
"p4mcp-server",
"--readonly",
"--allow-usage"
],
"env": {
"P4PORT": "ssl:<YOUR_PERFORCE_HOST>:1666",
"P4USER": "<YOUR_P4USER>",
"P4CLIENT": "<YOUR_P4CLIENT>"
}
}
}
}
