# Mcp Python Code Interpreter

> Python Code Interpreter MCP server

- **Type:** MCP server
- **Install:** `agentstack add mcp-khshanovskyi-mcp-python-code-interpreter`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [khshanovskyi](https://agentstack.voostack.com/s/khshanovskyi)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [khshanovskyi](https://github.com/khshanovskyi)
- **Source:** https://github.com/khshanovskyi/mcp-python-code-interpreter

## Install

```sh
agentstack add mcp-khshanovskyi-mcp-python-code-interpreter
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MCP Python Code Interpreter

A stateful Python code execution environment with Jupyter kernel support, built on the Model Context Protocol (MCP). Execute Python code with persistent state, automatic visualization handling, and secure session management.

## Features

- **Stateful Execution**: Variables, imports, and state persist across multiple code executions within a session
- **Jupyter Kernel Backend**: Full Jupyter kernel support with IPython features
- **Session Management**: Secure session IDs with automatic 30-minute timeout
- **Visualization Support**: Automatic capture and export of matplotlib, seaborn, and Plotly figures
- **File Generation**: Access generated files (images, data files, plots) via MCP resources
- **Scientific Computing**: Pre-configured with pandas, numpy, matplotlib, seaborn, plotly, and sympy
- **Automatic Cleanup**: Background task removes expired sessions and orphaned files

## Installation

### Using Docker (Recommended)

```bash
# Build the image
docker build -t mcp-python-interpreter .

# Run the container
docker run -p 8000:8000 mcp-python-interpreter
```

### Local Installation

```bash
# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Run the server
python server.py
```

## Usage

The server exposes three tools and a resource endpoint for file access.

### 1. Execute Code

Execute Python code in a persistent Jupyter kernel environment.

**First execution (creates new session):**
```python
{
  "code": "import pandas as pd\nx = 42\nprint('Hello, World!')",
  "session_id": ""  # Empty string or "0" for new session
}
```

**Response:**
```json
{
  "success": true,
  "output": ["Hello, World!\n"],
  "result": null,
  "session_info": {
    "session_id": "abc123xyz456",
    "instructions": "Use this `session_id` in subsequent requests..."
  }
}
```

**Subsequent executions (reuse session):**
```python
{
  "code": "print(x * 2)  # Variable persists from previous execution",
  "session_id": "abc123xyz456"
}
```

### 2. Create Visualizations

Matplotlib, seaborn, and Plotly figures are automatically captured and saved.

```python
{
  "code": """
import matplotlib.pyplot as plt
import numpy as np

x = np.linspace(0, 10, 100)
plt.plot(x, np.sin(x))
plt.title('Sine Wave')
plt.savefig('sine_wave.png')
plt.show()
""",
  "session_id": "abc123xyz456"
}
```

**Response includes file references:**
```json
{
  "success": true,
  "output": ["📊 File created: sine_wave.png (image/png, 45231 bytes)"],
  "files": [
    {
      "uri": "kernel://abc123xyz456/sine_wave.png",
      "mime_type": "image/png",
      "name": "sine_wave.png",
      "size": 45231
    }
  ]
}
```

### 3. List Session Files

```python
{
  "session_id": "abc123xyz456"
}
```

### 4. Clear Session

Manually remove a session and all its files:

```python
{
  "session_id": "abc123xyz456"
}
```

### 5. Access Files

Files are accessed via the MCP resource protocol:

```
kernel://{session_id}/{filename}
```

Example: `kernel://abc123xyz456/sine_wave.png`

## Session Management

### Session Lifecycle

1. **Creation**: First call with empty `session_id` generates a secure 16-character ID
2. **Active**: Session remains active while being used
3. **Timeout**: Sessions expire after **30 minutes of inactivity**
4. **Cleanup**: Expired sessions are automatically removed (background task runs every 5 minutes)

### Session Expiration

If you try to use an expired session, you'll receive a `SessionExpiredError`:

```json
{
  "success": false,
  "error": "SessionExpiredError: Session abc123xyz456 not found or has expired...",
  "traceback": []
}
```

**Solution**: Create a new session and re-execute your setup code.

## Available Libraries

The following libraries are pre-installed:

- **Data Science**: pandas, numpy
- **Visualization**: matplotlib, seaborn, plotly, kaleido
- **Mathematics**: sympy
- **Jupyter**: ipykernel, jupyter-client

Additional packages can be installed at runtime using `!pip install` within your code.

## Configuration

### Environment Variables

- `LOG_LEVEL`: Logging level (default: `INFO`)
- `JUPYTER_PLATFORM_DIRS`: Set to `1` (suppresses Jupyter warnings)

### Server Configuration

Edit `config.py` to modify:

```python
NOTEBOOKS_FOLDER = ROOT_DIR / 'notebooks'  # Session storage location
KERNEL_TIMEOUT = 10  # Kernel operation timeout (seconds)
```

Edit `server.py` to modify:

```python
SESSION_TIMEOUT = 30 * 60  # Session expiration (seconds)
```

## API Reference

### Tools

#### `execute_code`

Execute Python code in a persistent Jupyter kernel environment.

**Parameters:**
- `code` (str): Python code to execute (multi-line supported)
- `session_id` (str, optional): Session identifier (empty or "0" for new session)

**Returns:**
- `success` (bool): Execution status
- `output` (list): stdout/stderr text
- `result` (str|None): Last expression value
- `error` (str|None): Error message if failed
- `traceback` (list): Full traceback if error
- `files` (list): File references with URIs
- `session_info` (dict|None): Session info for new sessions

#### `list_session_files`

List all files generated in a session.

**Parameters:**
- `session_id` (str): Session identifier

**Returns:**
- `session_id` (str): The session ID
- `files` (list): List of file references
- `error` (str): Error message if session not found

#### `clear_session`

Manually clear a session and shutdown its kernel.

**Parameters:**
- `session_id` (str): Session identifier to clear

**Returns:**
- `success` (bool): Operation status
- `message` (str): Status message

### Resources

#### `kernel://{session_id}/{filename}`

Retrieve file content from a session.

**URI Format:** `kernel://session_id/filename`

**Returns:** File content (binary for images, text for text files)

## Architecture

```
┌─────────────────┐
│  MCP Client     │
│  (Claude, etc)  │
└────────┬────────┘
         │
         │ MCP Protocol
         │
┌────────▼────────┐
│    MCP Server   │
│  (server.py)    │
└────────┬────────┘
         │
         │ Manages
         │
┌────────▼────────┐
│ Session Manager │
│ - Create/Track  │
│ - Cleanup       │
└────────┬────────┘
         │
         │ Controls
         │
┌────────▼────────┐
│ Jupyter Kernels │
│ (per session)   │
└─────────────────┘
```

## Development

### Project Structure

```
mcp-python-code-interpreter/
├── config.py          # Configuration and initialization
├── models.py          # Pydantic data models
├── notebook.py        # Jupyter kernel management
├── server.py          # MCP server and tools
├── Dockerfile         # Docker configuration
├── requirements.txt   # Python dependencies
└── notebooks/         # Session storage (auto-created)
```

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [khshanovskyi](https://github.com/khshanovskyi)
- **Source:** [khshanovskyi/mcp-python-code-interpreter](https://github.com/khshanovskyi/mcp-python-code-interpreter)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-khshanovskyi-mcp-python-code-interpreter
- Seller: https://agentstack.voostack.com/s/khshanovskyi
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.