PyScriptor MCP Server

A Model Context Protocol (MCP) server for Python code execution and REPL interaction using Jupyter kernels.

Features

🐍 py-execute

Execute Python code in a new subprocess and get results immediately.

• Returns stdout, stderr, execution time, and success status
• Configurable timeout (default: 30 seconds)
• Safe subprocess execution with proper cleanup

🔄 REPL Session Management

Manage persistent Python REPL sessions powered by Jupyter kernels.

• start_repl: Create a new Python REPL session
• execute_in_repl: Execute code in existing session (variables persist)
• list_repls: View all active sessions with status info
• kill_repl: Terminate a specific session
• kill_all_repls: Terminate all sessions

Installation & Setup

Prerequisites

• Python 3.13+
• UV package manager
• Claude Desktop

1. Install Dependencies

uv sync

2. Test the Server

uv run python test_client.py

3. Configure Claude Desktop

Windows

1. Open Claude Desktop
2. Click Settings → Developer tab → Edit Config
3. Add this configuration to claude_desktop_config.json:

{
  "mcpServers": {
    "pyscriptor": {
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "D:/project/pyscript-mcp",
      "env": {}
    }
  }
}

Alternative: Use Batch Script

{
  "mcpServers": {
    "pyscriptor": {
      "command": "D:/project/pyscript-mcp/run_server.bat",
      "args": [],
      "cwd": "D:/project/pyscript-mcp",
      "env": {}
    }
  }
}

4. Restart Claude Desktop

Close and restart Claude Desktop completely for changes to take effect.

Usage Examples

Quick Code Execution

Can you calculate 2^10 using Python?

Uses py-execute to run: print(2**10)

Persistent REPL Session

Start a Python REPL session and create some variables for data analysis.

Creates a new REPL session and sets up variables that persist between commands

Data Analysis Workflow

1. Start a Python REPL session
2. Import pandas and numpy
3. Create a sample dataset
4. Perform some analysis
5. Show me the session status

Architecture

• PythonExecutor: Handles one-time code execution via subprocess
• JupyterReplSession: Manages individual Jupyter kernel sessions
• JupyterReplManager: Coordinates multiple REPL sessions
• FastMCP Integration: Provides MCP protocol compliance

Security

• All code execution requires explicit user approval in Claude Desktop
• Each REPL session runs in an isolated Jupyter kernel
• Subprocess execution with proper timeout and cleanup
• No automatic code execution without user consent

Troubleshooting

Server Won't Start

• Check UV is installed: uv --version
• Verify Python 3.13+ is available
• Check project dependencies: uv sync

Claude Desktop Won't Connect

• Ensure config file path is correct
• Verify absolute paths in configuration
• Check Claude Desktop logs for connection errors
• Restart Claude Desktop after config changes

REPL Sessions Not Working

• Check Jupyter dependencies are installed
• Verify kernel can start: uv run python -c "from jupyter_client import KernelManager; print('OK')"
• Check for port conflicts or permission issues

Development

Run Tests

uv run python test_client.py
uv run python debug_test.py
uv run python debug_py_execute.py

Project Structure

pyscript-mcp/
├── main.py              # FastMCP server entry point
├── python_executor.py   # Core execution logic
├── test_client.py       # Test suite
├── run_server.bat       # Windows startup script
├── pyproject.toml       # Project configuration
└── README.md           # This file

License

This project is for educational and development purposes.