MCP Python Interpreter

Overview Schema Source Related Servers Discussions Admin

run_python_code

Execute Python code in-process for stateful sessions or in an isolated subprocess when environment separation is needed, saving files and enforcing timeouts.

Instructions

Execute Python code with flexible execution modes.

Args:
    code: Python code to execute
    execution_mode: Execution mode - "inline" (default, fast, in-process) or "subprocess" (isolated)
    session_id: Session ID for inline mode to maintain state across executions
    environment: Python environment name (only for subprocess mode)
    save_as: Optional filename to save the code before execution (within --dir by default)
    timeout: Maximum execution time in seconds (only enforced for subprocess mode)
    overwrite: Allow replacing an existing save_as file (default: False)

Returns:
    Execution result with output

Execution modes:
- "inline" (default): Executes code in the current process. Fast and reliable,
  maintains session state. Use for most code execution tasks.
- "subprocess": Executes code in a separate Python process. Use when you need
  environment isolation or a different Python environment.

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "code": "<code>"
    },
    "name": "run_python_code"
  }
}

Input Schema

Name	Required	Default
`code`	Yes
`save_as`	No
`timeout`	No
`overwrite`	No
`session_id`	No	default
`environment`	No	system
`execution_mode`	No	inline

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedv1.2.5Nov 1, 2026

addedInput schema / properties / overwrite

Added value: +{
+  "default": false,
+  "title": "Overwrite",
+  "type": "boolean"
+}

Changed5 schema fields changedv1.0.0Jan 2, 2026

changedInput schema / properties / environment / default
```
Previous value: -"default"New value: +"system"
```

addedInput schema / properties / execution_mode

Added value: +{
+  "default": "inline",
+  "title": "Execution Mode",
+  "type": "string"
+}

addedInput schema / properties / session_id

Added value: +{
+  "default": "default",
+  "title": "Session Id",
+  "type": "string"
+}

addedInput schema / properties / timeout

Added value: +{
+  "default": 300,
+  "title": "Timeout",
+  "type": "integer"
+}

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "properties": {
+    "result": {
+      "title": "Result",
+      "type": "string"
+    }
+  },
+  "required": [
+    "result"
+  ],
+  "title": "run_python_codeOutput",
+  "type": "object"
+}

First observedAug 18, 2025

TDQS

A4/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden and does well: it discloses that inline runs in-process and persists state via session_id, that subprocess is isolated, and critically that timeout is only enforced in subprocess mode and save_as writes within --dir. It omits side-effect/security notes (arbitrary code execution risk, output truncation) and the default timeout value.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with the purpose, then Args/Returns/modes in a predictable structure. The execution_mode meaning is stated twice (once in Args, once in the modes section), a minor redundancy that costs a little tightness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter execution tool with no annotations, the description covers mode semantics, state persistence, and the timeout caveat, and an output schema exists so return values needn't be detailed. Sibling disambiguation against run_python_file is the remaining gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate and largely does, explaining all seven parameters including the mode-dependent scope of environment and timeout and the overwrite gate on save_as. It omits the default values (timeout 300, session_id "default") and any format detail for save_as beyond the --dir note.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb and resource ('Execute Python code') and names the two execution modes. It is clear what the tool does, but it never distinguishes itself from the sibling run_python_file, which an agent must choose between.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly recommends "inline" for "most code execution tasks" and "subprocess" for environment isolation or a different Python environment, which is real routing guidance. It gives no guidance on when to use this vs run_python_file, or when a fresh session_id / clear_session is warranted.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Deploy Server