mypr MCP server
Commit Oct 19, 2026Provides a persistent, workspace-scoped Python runtime that allows LLM agents to execute code, manage files, and run shell commands.
Also known as prepaser/mypr-mcp
- Stars
- 0
- Tools
- 3
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 19, 2026
- License
- AGPL-3.0
What is mypr MCP?
mypr provides a persistent, workspace-scoped Python runtime that allows LLM agents to execute code, manage files, and run shell commands. It exposes 3 tools, such as init, execute, poll.
Summary generated from the project's README
About mypr MCP server
Providing a persistent, workspace-scoped Python environment for LLM agents is what mypr-mcp enables. It creates a dedicated Python kernel for a specific directory, allowing agents to maintain variables, imports, and functions across different connections. This setup is designed for Linux users running Python 3.14 and uses uv for package management and execution.
Agents interact with the workstation through a unified Python API that includes tools for file operations, shell commands, Git, web search, and browser automation. The server runs locally via stdio, and users can launch it using the uvx command. Because the manager process continues running even after a client disconnects, an agent can resume a session and access the same in-memory state by reconnecting to the existing workspace. This makes it ideal for long-running development tasks where state persistence is required.
What you can do with it
- 1Maintain state across sessionsAn agent can reconnect to a workspace to reuse previously defined variables and functions.
- 2Execute long-running background tasksDevelopers can hand off complex shell commands to an agent that runs independently of the immediate request.
- 3Automate system diagnostics and file managementAn AI client can be instructed to perform network scanning or edit files using the workspace API.
- 4Manage complex shell workflowsAn agent can start a process like a test suite and monitor its output over time.
Written from the project's README. Every use case is checked against a quote from it.
mypr MCP tools 3
Detected from the READMEinitexecutepoll
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachableprepaser/mypr-mcp is public and reachablegithub.com/prepaser/mypr-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)AGPL-3.0spdx.org/licenses/AGPL-3.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-10-19github.com/prepaser/mypr-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model3 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubmypr-mcp
mypr-mcp provides a persistent, workspace-scoped Python layer between an LLM agent and the workstation. Each workspace has one Python kernel. Every MCP connection opened for that workspace shares the same variables, imports, functions, and background-task handles.
It provides a development toolkit for LLM agents: file operations, code and document search, web search, Git, shell commands, HTTP, browser automation, network scanning, and system diagnostics through one Python API. Agents can combine these tools in scripts and extend the environment with reusable Python functions, skills, and external MCP integrations.
The runtime is intended for Linux, Python 3.14, and uv.
Run
Install uv, then configure your MCP client to launch:
uvx mypr-mcp serve
The client communicates with the server over stdio. The server's working directory becomes the workspace, so configure the client to launch it from the directory where the agent should work. uvx downloads and runs the package automatically.
For clients using mcpServers JSON configuration:
{
"mcpServers": {
"mypr": {
"command": "uvx",
"args": ["mypr-mcp", "serve"]
}
}
}
Make sure uvx is on the client's PATH, or use its absolute executable path.
Codex
[mcp_servers.mypr]
command = "uvx"
args = ["mypr-mcp", "serve"]
startup_timeout_sec = 180
tool_timeout_sec = 60
required = true
uvx must be on Codex's PATH; use its absolute executable path if needed.
Alternatively, register the launch command through the CLI:
codex mcp add mypr -- uvx mypr-mcp serve
Workspace runtime
The first start creates .mypr/ in the launch workspace, its Python environment, and a manager process. The manager and kernel continue running after an MCP client disconnects, so another client for the same workspace reconnects to the same in-memory environment.
Symlink and bind-mount aliases of the same directory connect to the same workspace runtime. Discovery uses the directory's filesystem device and inode, not its path string. The identity is visible as workspace_id in runtime status and .mypr/runtime.json; copying a workspace creates a separate identity.
Clients must run as the same OS user and be able to reach the runtime socket. When using separate mount namespaces or containers, share the runtime directory ($XDG_RUNTIME_DIR/mypr, or /tmp/mypr-<uid>/mypr when unset). The recorded socket also allows discovery when clients use different runtime-directory settings, provided that socket remains accessible. An unreachable existing manager is reported instead of launching a duplicate.
On Linux, each Unix socket pathname is limited to 107 bytes. The manager and kernel append their workspace identifier and channel suffixes beneath the runtime directory, so use a short XDG_RUNTIME_DIR. New-manager startup reports an actionable error if these paths exceed the limit. A recorded, accessible socket can still reconnect to an existing manager when the current runtime-directory setting is longer.
Stop the manager before moving a workspace, then start it at the new location. A same-filesystem rename preserves directory identity, but Python objects, venv entry points, and external MCP configurations can contain old absolute paths; these are not rewritten automatically. If the original directory is moved or replaced while running, new attachments and cells are rejected with a restart instruction. Status and stop remain available through the discovered socket.
MCP tools
Three tools are exposed to the agent:
init(client_id=None)binds this MCP connection to a logical client. With no argument, it allocates a new readable ID such ascalm-otter; with an argument, it creates or resumes that ID. The returned ID is bound to the connection, so later calls do not repeat it.execute(code, wait_ms=None, request_id=None, max_bytes=None)submits a Python cell and returns its execution state and output. The connection must be initialized first. An omittedwait_msuseslimits.execute_wait_ms(1,000 ms by default); an explicit value, including0, overrides it for that call.wait_msonly controls how long the MCP call waits; it does not set a Python timeout.poll(exec_id, cursor=None, wait_ms=None, max_bytes=None)reads a submitted cell's state and output. Use the returned cursor to read later output. Polling an existing execution is allowed beforeinit, since the execution ID identifies the target. An omittedwait_msuseslimits.poll_wait_ms(1,000 ms by default); an explicit value, including0, overrides it for that call.max_bytescontrols one response page and accepts 1 KiB–1 MiB; when omitted, the workspace's configured response limit is used.
Tool responses provide readable text in content and the complete machine-readable payload in structuredContent. The text includes the current output page in full, with execution state, cursor, errors, warnings, and inbox previews. Adjacent fragments of the same stream are combined for display; the structured events and their cursors are unchanged. Initialization and runtime changes also include the running manager's API instructions.
Clients must parse structuredContent (the Python MCP SDK exposes result.structured_content), rather than treating text blocks as JSON. For older servers, a client may fall back to parsing their JSON text when structured content is absent. The new text format intentionally no longer mirrors the complete JSON payload.
When an operation fails, inspect both the bounded error string and the optional error_info object. error_info.code identifies categories such as conflict, dependency_missing, timeout, invalid_cursor, outcome_unknown, and python_exception; operation and bounded details provide machine-readable context. Branch on the code and inspect the execution or transaction ID before retrying a state-changing operation.
For a failed shell or package job, the error details may also include its task id, state, and known returncode. A missing return code means the command's exit status was not confirmed; do not infer success from an empty output page.
execute waits for completion, inbox activity, or its wait deadline so short cells normally need only one call. poll returns immediately when the requested output is available or the execution is terminal; otherwise it waits for output, completion, inbox activity, or its wait deadline. wait_ms bounds this notification wait, not total request latency or Python execution time. The configured defaults are limits.execute_wait_ms and limits.poll_wait_ms, each an integer from 0 through 30,000 milliseconds. Continue polling running cells, and read remaining pages while has_more is true even after execution finishes.
The init, execute, and poll responses include small previews of the current client's unacknowledged inbox and expired timers. Message previews contain up to five messages and fit within a 4 KiB JSON budget; timer previews contain up to five alerts in the same budget. Reading a preview or receiving a timer alert does not acknowledge it. Use ws.messages.read() and ws.timers.list() for full records. Before init, poll omits the inbox and timer previews.
Call init() before the first execute:
init() -> binds calm-otter and returns runtime guidance
execute(code="...", ...) -> uses calm-otter automatically
poll(exec_id="...", ...) -> reads the execution
Repeating init() or specifying the currently bound ID returns that same ID. Trying to bind an initialized connection to a different ID is rejected. Only one live MCP connection may use a logical client ID at a time; after disconnecting, another connection can call init(client_id="calm-otter") to resume it. A connection that has not called init can still be counted and inspected by operational status, but it cannot submit Python code.
Submitted cells run as independent asyncio tasks in the shared kernel. They may complete in a different order from submission, including cells from the same client. An await that is still pending yields to other cells; synchronous code, synchronous IPython magics, and CPU-heavy work continue to occupy the event loop. If one cell depends on another, wait for the prerequisite to complete before submitting the dependent cell.
Use a background handle when work should remain detached from the submitting cell:
job = await ws.shell.start("make -j2")
The cell returns after the process is started. In a later cell:
job.status()
job.output()
job.result()
await job.cancel()
result() raises NotReady until completion. await job explicitly waits for completion of that job; for persist_result=True, it also waits for the persistence attempt and terminal publication to settle while returning the original in-memory value. Use await job.wait_saved() when the caller needs confirmed saved JSON; it returns None on success and raises ResultUnavailable when saving is unavailable, unserializable, unknown, or later removed by retention. Calling it for a live job without persist_result=True raises ValueError. Cancelling the wait does not cancel the job or its reporter. Other async cells continue to run. Use ws.tasks.list() and ws.tasks.get(task_id) to find handles created in another session. A disconnected MCP client does not cancel its submitted cells or background jobs.
Python workspace API
The kernel injects ws, a Workspace instance, into every Python cell. Imports and globals are shared; use ws.local for client-specific scratch state.
print(ws.help())
print(ws.help("fs"))
await ws.fs.write("notes.txt", "Hello from Python.\n")
The Python workspace API guide covers entry points, examples, dependency preparation, and result paging. Detailed guides cover configuration, code navigation, media and documents, and workspace storage.
Common workflows
Use shell.run() for a short command. Pass an argument list when shell syntax is not needed; a nonzero exit is returned in returncode, while check=True raises ShellError.
result = await ws.shell.run(["git", "status", "--short"])
print({
"state": result["state"],
"returncode": result["returncode"],
"truncated": result["truncated"],
"warnings": result.get("warnings", []),
})
print(result["stdout"])
print(result["stderr"])
Use shell.start() for long work. Keep the handle and its bounded read() cursor in ws.local, print the task ID for later reconnection, and inspect the terminal status before awaiting the final result. A cell completing only means that the nested job was started or inspected.
ws.local["job"] = await ws.shell.start(["pytest", "-q"])
print(ws.local["job"].id)
page = await ws.local["job"].read(max_bytes=32768, wait_ms=1000)
ws.local["job_cursor"] = page["cursor"]
print({
"state": page["state"],
"has_more": page["has_more"],
"truncated": page["truncated"],
"warnings": page.get("warnings", []),
})
print(page["output"])
For search, inspect the first page's complete and stop_reason; use ws.pages.iter(...) only when every page is needed. For file edits, read and retain revision, preview a patch(dry_run=True), then apply with that revision. If it conflicts, reread the file before creating a new patch.
If the handle is still in the current kernel, use ws.tasks.get(task_id). After reset, reconnect with await ws.tasks.attach(task_id) using the ID you saved. Reconnection restores persisted status and output, not Python memory or arbitrary local variables. See the canonical workflows and cursor glossary.
Reset and lifecycle
await ws.reset() resets the shared Python memory for every agent connected to the workspace. By default it is rejected while any other cell or managed job is active. Pass force=True to cancel that work and reset. New Python tasks are rejected while a reset or restart request is being admitted, so they cannot escape the active-work check. Lifecycle and MCP management methods require an actual boolean for force; strings and integers are rejected. The reset cell's completion is reported by execute/poll. Saved files, skills, modules, package environment, and run records remain. The kernel generation changes and old Python job handles expire. Historical MCP execution IDs remain readable. Reusing a request ID within the same client returns the original execution instead of repeating side effects, including after a kernel reset or reconnecting with the same ID. Resuming that ID after a manager restart also retains request deduplication. A newly allocated ID starts a separate request-ID scope; use history to check earlier executions before retrying an uncertain operation.
reset only resets shared kernel memory. Globals, imports, functions, ws.local, and in-memory handles are lost; files, skills, modules, the package environment, messages, history, and saved task output remain.
Use await ws.restart() when a running workspace must apply the installation that made the request. This replaces the manager and kernel through a detached workspace coordinator, then reconnects planned MCP clients. It is explicit: package resolution and downloads belong to the command that launched the client (for example, uvx mypr-mcp@latest); restart does not resolve a new version from the network by itself. The default refuses while another cell, shell, scan, package job, or Python task is active. Use await ws.restart(force=True) to cancel active work first. The restart call's execution result is recorded and can be retrieved with poll; its Python code is never replayed.
The equivalent CLI command is:
cd /absolute/path/to/workspace
uvx mypr-mcp@latest restart
# Use --force only when cancelling active work is intended.
uvx mypr-mcp@latest restart --force
The new manager starts only after the old one exits and passes its health check. The coordinator records its ID, phase, old and new generation, target installation, and failure details under .mypr/. A rejected kernel restart does not launch a coordinator. If an accepted restart fails before stopping the old manager, its surviving kernel resumes accepting work once recovery completes. A failed start is reported without automatic rollback or an unbounded restart loop; inspect .mypr/manager.log, uvx diagnostics, and the restart record before retrying. External browser processes and pre-existing tabs remain owned by their launcher. Managed resources close during a normal replacement. Successful replacement clears in-memory Python state, while files, skills, modules, the package environment, messages, history, saved output, and completed scan records persist.
The CLI also provides operational controls. Run them from the workspace:
cd /absolute/path/to/workspace
uvx mypr-mcp status
uvx mypr-mcp doctor
uvx mypr-mcp logs
uvx mypr-mcp logs --limit 50 --follow
uvx mypr-mcp reset
uvx mypr-mcp restart
uvx mypr-mcp stop
logs prints JSONL lifecycle and output events. Without --follow it prints the most recent 20 events; --limit changes the page size (1–200). --follow waits for new records until interrupted. Use ws.history.logs(client_id=...) inside Python to filter by caller. The commands are local administration commands, not MCP tools. reset and stop reject active work unless --force is supplied. CLI stop reports success only after the original manager exits, so it is safe to reconnect immediately. Shutdown taking more than 30 seconds reports an error. Status includes the manager pid, protocol_version, manager and client installation versions, capabilities, update_pending, and a health_error when an essential runtime worker fails. Compatible package versions reuse the existing manager and kernel, so installing a newer uvx package alone does not clear Python memory. A protocol mismatch or an unknown legacy manager is reported through initialization with an actionable restart instruction rather than being hidden as a generic MCP handshake failure. The legacy 0.9.0 runtime has no ws.restart(); run the CLI restart once from the new installation to perform the first explicit replacement.
Automatic reconnection requires the updated MCP frontend; older frontend processes must be reopened once after installation.
Manager attachment has a 30-second handshake deadline, and rebinding a logical client ID has a separate 30-second deadline. Cold startup waits up to 180 seconds for readiness, including status-response waits; cleanup of an owned process follows a failed start.
Planned restart keeps the MCP stdio connection alive. After replacement, the connection receives a new connection ID and generation and rebinds its existing logical client ID. Other clients reconnect the same way. No submitted cell is replayed; use its recorded execution ID with poll. An ordinary crash, unplanned stop, or unreachable runtime does not trigger this reconnect path: unfinished executions become lost, and Python memory must be recreated.
Shell/package commands and local stdio MCP servers run through a supervisor. The supervisor's Python interpreter ignores Python-specific environment settings, while the command receives its configured environment unchanged. The supervisor closes its own standard streams after spawning the command, so it does not hold a terminated command's stdin/stdout pipes open. If the manager dies, their process groups receive SIGTERM, followed by SIGKILL after two seconds if needed. Same-group descendants remain supervised even after the original command exits. Processes that deliberately start a separate session are outside this boundary. HTTP MCP shutdown closes the local connection.
Python memory and running handles survive normal client disconnects, but they cannot be restored after a manager or kernel crash. In that case unfinished executions are marked lost; mypr-mcp never silently re-runs code or external MCP calls. The saved .mypr/runs/ records and files remain available for inspection. The logical client ID and its history remain available, so a new connection can call init(client_id="calm-otter") after the runtime is healthy; in-memory variables and local state must be recreated after a crash.
Output limits
Execution output is retained up to 16 MiB per run by default. Text events are paged with a default 32 KiB UTF-8 JSON budget, and poll uses cursors to retrieve later events. This is an output-page budget, not a limit on the entire MCP response: metadata, the readable text representation, inbox previews, and inline images add to it. Excess retained output is consumed and marked as truncated. Non-text display data is stored under .mypr/artifacts/.
If a cell cannot publish completion through its output channel, it reports its outcome through fallback RPC. Earlier output may not have arrived, so the saved result sets truncated=true and includes an output_incomplete warning. Reset also marks output incomplete when its ordered output barrier cannot be confirmed within three seconds or uses fallback RPC. This does not change the cell's execution outcome.
Inline PNG/JPEG images share a 2 MiB source-byte budget per response; base64 encoding increases their wire size. Images that exceed this budget are omitted from inline content, with their artifact paths and reasons retained in the response. Their files remain available for later inspection. Image reads are bounded even if a file grows after its metadata is checked. Malformed display items and unavailable image files produce bounded warnings without changing successful Python execution to failure. Valid text, execution state, cursors, and inbox data remain available. Excess warnings are indicated by warnings_truncated. Shell and package jobs report output persistence failures through warnings in job.status() and job.output(cursor=0). Python tasks drain retained output before publishing completion. Each result or lifecycle reporting RPC has a 10-second response deadline, independent of the Python task duration. After an output write cannot be confirmed, the reporter stops sending further output deltas and still attempts result and terminal reporting. An unconfirmed output write marks saved output as truncated and reports task_output_persistence_unknown in task status and history; the in-memory output remains readable. Their exit status still describes the command itself, and output continues to be drained after a storage failure. Historical polling preserves readable journal entries and replaces damaged lines with warning events, keeping event cursors stable. Cold polling after output retention expires returns output_evicted=true, truncated=true, and an output_expired warning; it does not present deleted output as complete empty output. journal_truncated identifies an incomplete final line; journal_corrupt identifies other invalid records. The original journal is left unchanged. The error field is a bounded summary (at most 1 KiB, smaller for small response budgets); error_truncated marks shortened summaries. Detailed traceback output is paged subject to the normal output limit.
mypr MCP questions
What tools does mypr MCP provide?
It exposes 3 tools, including init, execute, poll.
How do I run mypr-mcp?
You can install uv and then launch the server using the command uvx mypr-mcp serve.
What happens to the Python environment when an MCP client disconnects?
The manager and kernel continue running, allowing a new client to reconnect to the same in-memory environment and shared variables.
Can I run long-running shell commands?
Yes, you can use ws.shell.start() for long-running work and keep a handle to inspect its status and output.
Does the server support web search and browser automation?
Yes, the toolkit includes web search and browser automation among its other capabilities.