GitHub - ozgureyilmaz/mcp-code-execution: mcp code execution

MCP Code Execution Server

A powerful, secure, and stateful code execution server for the Model Context Protocol (MCP).

This server turns your AI assistant into a capable data analyst by providing:

Stateful Python Execution: Define variables and use them in subsequent calls (REPL-style)
Data Visualization: Automatically captures matplotlib plots and returns them as images
File System Access: Read and write files securely within a dedicated workspace
Package Management: Install any Python package on the fly

Inspired by: Code Execution with MCP - Anthropic's article on implementing code execution with MCP

Quick Start

Prerequisites

uv (Recommended) or Python 3.10+

Installation

# Clone the repository
git clone https://github.com/ozgureyilmaz/mcp-executor.git
cd mcp-executor

# Create virtual environment and install dependencies
uv venv
uv pip install -e .

Usage

Running the Server

The server communicates via stdio. To use it with an MCP client (like Claude Desktop), configure it as follows:

{
  "mcpServers": {
    "executor": {
      "command": "/Users/yourusername/dev/mcp-executor/.venv/bin/python",
      "args": ["-m", "mcp_executor.server"],
      "cwd": "/Users/yourusername/dev/mcp-executor"
    }
  }
}

Important: Replace /Users/yourusername/dev/mcp-executor with your actual project path.

Available Tools

Tool	Description
`execute_python`	Execute Python code. Preserves state between calls. Returns text output and plots.
`install_package`	Install a Python package (e.g., `pandas`, `numpy`).
`read_file`	Read a file from the `./workspace` directory.
`write_file`	Write content to a file in the `./workspace` directory.
`list_files`	List files in the `./workspace` directory.

Examples

Check the examples/ directory for usage examples.

Security

Workspace Isolation: File operations are strictly limited to the ./workspace directory
Local Execution: Code runs locally on your machine. Ensure you trust the code being executed
Package Installations: Packages are installed in the isolated virtual environment

Project Structure

mcp-executor/
├── src/
│   └── mcp_executor/
│       ├── __init__.py       # Package initialization
│       ├── __main__.py       # Direct module execution
│       ├── server.py         # MCP server implementation
│       └── execution.py      # Code execution layer
├── examples/                 # Example scripts
├── pyproject.toml           # Project configuration
└── README.md                # This file

Resources

Code Execution with MCP - Anthropic's article that inspired this project
MCP Protocol Documentation
MCP Debugging Guide

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.