Hugging Face's logo

Spaces:
MCP-1st-Birthday
/
PyMCP
Sleeping

App Files Community
PyMCP / README.md
aniketppanchal's picture
aniketppanchal
Added PyMCP
3b93525
preview code
|
raw
history blame contribute delete
9.51 kB
metadata 
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

PyMCP

A powerful MCP server for AI agents that uses Docker sandboxing to securely run Python code.
Unlike other solutions, it allows agents to install both system-level and Python dependencies and export generated files.

1. Demo 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 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

5.2. Image Preprocessing & Augmentation

6. Quickstart

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

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:

{
    "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.

pip install langchain langchain-mcp-adapters langchain-openai

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())

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 

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 

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

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 

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

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
MIT License | Built with Gradio ❤️