README.md

---
title: PyMCP
emoji: 🔥
colorFrom: pink
colorTo: yellow
sdk: docker
pinned: true
license: mit
short_description: A powerful MCP server for AI agents to run Python code.
tags:
- building-mcp-track-enterprise
- building-mcp-track-consumer
- building-mcp-track-creative
---

<table>
  <tr>
    <td width="15%" style="vertical-align: middle">
      <img
        src="https://github.com/aniketppanchal/mcp-1st-birthday-hackathon-assets/raw/refs/heads/main/py-mcp/logo.png"
      />
    </td>
    <td width="85%" style="text-align: center">
      <h1 style="font-size: 40px; margin: 0">PyMCP</h1>
      <p style="font-size: 16px; margin: 15px 0">
        A powerful MCP server for AI agents that uses Docker sandboxing to
        securely run Python code.<br />Unlike other solutions, it allows agents
        to install both system-level and Python dependencies and export
        generated files.
      </p>
      <div style="display: flex; justify-content: center">
        <img
          src="https://img.shields.io/badge/Python-3.11+-blue?style=for-the-badge&logo=python&logoColor=white"
          style="margin: 0 5px"
        />
        <img
          src="https://img.shields.io/badge/Docker-blue?style=for-the-badge&logo=docker&logoColor=white"
          style="margin: 0 5px"
        />
        <img
          src="https://img.shields.io/badge/Gradio-f97700?style=for-the-badge&logo=gradio&logoColor=white"
          style="margin: 0 5px"
        />
      </div>
    </td>
  </tr>
</table>

# 1. Demo Video

<video width="50%" controls>
  <source
    src="https://github.com/aniketppanchal/mcp-1st-birthday-hackathon-assets/raw/refs/heads/main/py-mcp/demo.mp4"
    type="video/mp4"
  />
  Your browser does not support the video tag.
</video>

# 2. Social Media Post

TODO: Update on the last day.

# 3. Why PyMCP Stands Out?

- **Full Control Without Limitations**

  Most of the MCP servers, which provide functionality to run Python code, always have some sort of limitation with them. For example, take [mcp-run-python](https://github.com/pydantic/mcp-run-python) by Pydantic; it uses WebAssembly isolation, which is a great thing for safety, but it does not provide any option for your AI agent to install any dependencies or to share generated files outside of the isolation. PyMCP has none of these limitations.

- **Supports Seamless File Export**

  Despite running inside a sandbox environment, PyMCP allows your AI agent to export generated files. This is made possible through Gradio’s `gr.File`, which can automatically generate downloadable URLs that can be local-only or public depending upon your configuration.

- **Truly General-Purpose**

  PyMCP is not limited to code execution; it can be seen as a generic capability layer for your agent. When provided instructions and context correctly, your agent can visualize CSVs, scrape websites, interact with APIs, process images, and generate reports. If it can be done using Python, your agent can do it with PyMCP.

- **Intentional Simplicity**

  Many MCP servers expose dozens of small, narrowly focused tools, and with an increased number of tools comes JSON schema complexity, more model context consumption, and a higher risk of tool misuse or hallucinations. PyMCP exposes only 3 simple tools: `execute_python_code`, `execute_shell_command`, and `export_files`.

- **Effortless Deployment**

  Deploying PyMCP is effortless. Simply build the Docker image and push it to Hugging Face Spaces or to any of the cloud providers you prefer. There is no infrastructure lock-in or vendor-specific setup.

# 4. Features

- **Docker Sandboxing**

  All execution happens inside the Docker sandbox; your host system remains untouched.

- **Shell Command Execution**

  Agents can execute shell commands inside the sandbox, which is useful for interacting with the sandbox environment.

- **Dependency Management**

  Agents can install both system-level and Python dependencies required to complete their tasks. For example, web scraping requires the Selenium package as well as a browser.

- **File Export**

  Agents can export generated files as downloadable URLs outside the sandbox. These URLs can be local-only or publicly accessible based on configuration.

- **Configurable Timeouts**

  Package installation, code execution, and shell command execution each have independent, configurable timeouts defaulting to 5 minutes to avoid long-running tasks.

- **Quickstart System Prompt**

  PyMCP includes a quickstart system prompt that provides additional context to agents. Users can pass it directly or incorporate it into their own system prompt.

- **Web UI**

  Powered by Gradio, PyMCP includes a minimal web interface to manually test tools and prompts.

# 5. Real-World Examples Using PyMCP

Examples are generated entirely inside the PyMCP Docker sandbox using Gemini 3 Pro.

### 5.1. Dataset Analysis

<img
  src="https://github.com/aniketppanchal/mcp-1st-birthday-hackathon-assets/raw/refs/heads/main/py-mcp/demo_image_1.png"
  width="600px"
/>

### 5.2. Image Preprocessing & Augmentation

<img
  src="https://github.com/aniketppanchal/mcp-1st-birthday-hackathon-assets/raw/refs/heads/main/py-mcp/demo_image_2.png"
  width="600px"
/>

# 6. Quickstart

You can get started instantly by using the deployed version of PyMCP:

> [!IMPORTANT]
> Use the following endpoints based on your use case:
>
> - Web Interface: `https://huggingface.co/spaces/MCP-1st-Birthday/PyMCP`
> - Streamable HTTP (MCP): `https://mcp-1st-birthday-pymcp.hf.space/gradio_api/mcp`
> - SSE (MCP): `https://mcp-1st-birthday-pymcp.hf.space/gradio_api/mcp/sse`

### 6.1. Claude Desktop (Requires npx)

Add/update your `claude_desktop_config.json`:

```json
{
	"mcpServers": {
		"py-mcp": {
			"command": "npx",
			"args": [
				"-y",
				"mcp-remote",
				"https://mcp-1st-birthday-pymcp.hf.space/gradio_api/mcp"
			]
		}
	}
}
```

### 6.2. LangChain

The example below also demonstrates PyMCP's built-in system prompt.

```bash
pip install langchain langchain-mcp-adapters langchain-openai
```

```python
import asyncio

from langchain.agents import create_agent
from langchain_mcp_adapters.client import MultiServerMCPClient


async def main() -> None:
    client = MultiServerMCPClient(
        {
            "py-mcp": {
                "transport": "streamable_http",
                "url": "https://mcp-1st-birthday-pymcp.hf.space/gradio_api/mcp",
            },
        }
    )

    system_prompt = (await client.get_prompt("py-mcp", "system_prompt"))[0].content
    tools = await client.get_tools()
    agent = create_agent(
        model="openai:gpt-5.1",
        system_prompt=system_prompt,
        tools=tools,
    )

    query = "Create a simple bar chart using matplotlib."
    response = await agent.ainvoke({"messages": query})
    print(response["messages"][-1].content)


if __name__ == "__main__":
    asyncio.run(main())
```

> [!IMPORTANT]
> When running inside a Jupyter notebook, use `await main()` instead of `asyncio.run(main())` since an event loop is already running.

# 7. Build & Run

### Prerequisites

- Docker
- Git

### 7.1. Clone and Build

```bash
git clone https://github.com/aniketppanchal/py-mcp.git
cd py-mcp
docker build -t py-mcp .
```

### 7.2. Run the Container

Choose one of the modes below:

#### 7.2.1. Local Mode

```bash
docker run --rm --name py-mcp-server -p 7860:7860 py-mcp
```

> [!IMPORTANT]
> Use the following endpoints based on your use case:
>
> - Web Interface: `http://localhost:7860`
> - Streamable HTTP (MCP): `http://localhost:7860/gradio_api/mcp`
> - SSE (MCP): `http://localhost:7860/gradio_api/mcp/sse`
>
> **Note:** It is not recommended to change the host port from `7860` to another value, as you would need to update the port in all endpoints above, including all the downloadable URLs provided by your agent.

#### 7.2.2. Online Mode

```bash
docker run --rm --name py-mcp-server -e SHARE_ONLINE=true py-mcp
```

> [!IMPORTANT]
> When running in online mode, Gradio will print a unique public URL, for example:
> `https://xxxx.gradio.live`
>
> Use the following endpoints based on your use case:
>
> - Web Interface: `https://xxxx.gradio.live`
> - Streamable HTTP (MCP): `https://xxxx.gradio.live/gradio_api/mcp`
> - SSE (MCP): `https://xxxx.gradio.live/gradio_api/mcp/sse`

### 7.2.3. Configuration Options

You can customize sandbox behavior using the following environment variables:

| Environment Variable             | Type             | Description                                                                | Default |
| -------------------------------- | ---------------- | -------------------------------------------------------------------------- | ------- |
| SHARE_ONLINE                     | `true` / `false` | Controls whether exported file URLs are publicly accessible or local-only. | `false` |
| PACKAGE_INSTALLATION_TIMEOUT_SEC | Number (seconds) | Maximum duration allowed for installing Python packages.                   | `600`   |
| CODE_EXECUTION_TIMEOUT_SEC       | Number (seconds) | Maximum duration allowed for Python code execution.                        | `600`   |
| COMMAND_EXECUTION_TIMEOUT_SEC    | Number (seconds) | Maximum duration allowed for shell command execution.                      | `600`   |

<div align="center">
	<strong>
		<a href="https://huggingface.co/spaces/MCP-1st-Birthday/PyMCP/blob/main/LICENSE">MIT License</a>
		| Built with <a href="https://www.gradio.app" target="_blank">Gradio</a> ❤️
	</strong>
</div>