# Python Interpreter MCP Server
[](https://github.com/deadmeme5441/python-mcp-server/actions)
[](https://pypi.org/project/python-mcp-server/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://deadmeme5441.github.io/python-mcp-server/)
A world-class Python interpreter MCP (Model Context Protocol) server that provides secure, isolated Python code execution with advanced session management and health monitoring. Built with FastMCP for production-grade reliability.
## ✨ Features
### 🚀 **Production-Ready Architecture**
- **FastMCP Middleware Stack**: Professional error handling, timing, and contextual logging
- **Session-Based Isolation**: Multiple independent Python kernels with complete state separation
- **Health Monitoring**: Real-time kernel diagnostics with intelligent restart capabilities
- **Progressive Timeouts**: Resilient execution with smart retry logic
### 🔒 **Security & Reliability**
- **Workspace Sandboxing**: Path traversal protection and secure file operations
- **Resource Monitoring**: CPU, memory, and process health tracking
- **State Preservation**: Automatic kernel state backup and restoration
- **Error Resilience**: Graceful handling of kernel failures and timeouts
### 🛠 **Developer Experience**
- **Notebook Surface**: One tool to run cells, manage datasets, and export artifacts
- **File Management**: Read, write, delete operations with safety checks
- **Package Installation**: Dynamic dependency management with uv/pip
### 🎯 **FastMCP Integration**
- **Native FastMCP Configuration**: Built-in `fastmcp.json` for easy deployment
- **CLI Integration**: Works seamlessly with FastMCP CLI commands
- **Multiple Transport Modes**: STDIO, HTTP, Server-Sent Events support
- **Claude Desktop Ready**: Perfect integration with Claude Desktop
## 🚀 Quick Start
### Installation
**Method 1: PyPI (Recommended)**
```bash
pip install python-mcp-server
```
**Method 2: uvx (Isolated)**
```bash
uvx install python-mcp-server
```
**Method 3: FastMCP CLI (For Claude Desktop)**
```bash
fastmcp install claude-desktop python-mcp-server
```
### Basic Usage
**Standalone Server (HTTP Mode)**
```bash
# Start HTTP server
python-mcp-server --host 127.0.0.1 --port 8000
# Custom workspace
python-mcp-server --workspace /path/to/workspace --port 8000
```
**FastMCP CLI (Recommended)**
```bash
# Run with FastMCP (auto-detects fastmcp.json)
fastmcp run
# Run with specific transport
fastmcp run --transport http --port 8000
# For development/testing
fastmcp dev
```
### Client Usage
**FastMCP Client**
```python
import asyncio
from fastmcp.client import Client
async def main():
async with Client("http://localhost:8000/mcp") as client:
# Execute Python code
result = await client.call_tool("run_python_code", {
"code": """
import numpy as np
import matplotlib.pyplot as plt
x = np.linspace(0, 10, 100)
y = np.sin(x)
plt.figure(figsize=(10, 6))
plt.plot(x, y, 'b-', linewidth=2)
plt.title('Sine Wave')
plt.grid(True)
plt.show()
print("Plot created successfully!")
"""
})
print("Output:", result.data["stdout"])
asyncio.run(main())
```
## 🏗 Architecture
```mermaid
graph TB
A[MCP Client] --> B[FastMCP Server]
B --> C[Session Manager]
C --> D[Kernel Session 1]
C --> E[Kernel Session 2]
C --> F[Default Session]
B --> G[Health Monitor]
G --> H[Resource Tracker]
G --> I[Timeout Handler]
B --> J[Workspace Manager]
J --> K[File Operations]
J --> L[Security Layer]
```
## 📦 Package Structure (v1.0.0)
```
src/python_mcp_server/
├── server.py # Main FastMCP server implementation
├── __init__.py # Package initialization
└── ...
fastmcp.json # FastMCP configuration
pyproject.toml # Package metadata and dependencies
tests/ # Comprehensive test suite
docs/ # Documentation source
```
## 🔧 Tools Reference
### Notebook (single surface)
`notebook(action=..., ...)` — one tool for cells, datasets, and exports.
- Actions:
- `run` — execute a cell; capture stdout/stderr, figures (PNG/SVG), JSON outputs, and a workspace diff. Writes a manifest per cell under `outputs/notebooks/<id>/`.
- `cells` — list executed cells (from index.json).
- `cell` — fetch one cell’s manifest.
- `export` — write a `.ipynb` (and `.html` if available) to `outputs/notebooks/`.
- `reset` — clear notebook manifests for the same `notebook_id` (kernel is not restarted).
- `datasets.register` — create/update a DuckDB VIEW over CSV/Parquet files or globs.
- `datasets.list` — show registered datasets.
- `datasets.describe` — schema + head(50).
- `datasets.drop` — remove a registered dataset/view.
- `datasets.sql` — run SQL across registered views; returns preview and writes full result to Parquet.
### Core Execution
- `run_python_code` - Execute Python with output capture (rich display assets saved to `outputs/`)
- `restart_kernel` - Clean kernel restart with optional state preservation
### File Operations
- `list_files` - Browse workspace (flat or tree view)
- `read_file` / `write_file` / `delete_file` - Safe file operations
### Package Management
- `install_dependencies` - Dynamic dependency installation with uv/pip fallback
## 💡 Advanced Usage
### Notes
- Session isolation, health and concurrency controls run under the hood; the public tool surface is intentionally minimal for agent reliability.
## 🧰 Interpreter / Venv Configuration
The server runs the Jupyter kernel with the same interpreter and environment as the process by default. You can override with flags in both stdio and http modes:
```bash
python-mcp-server \
--python /path/to/python \
--venv /path/to/venv \
--pythonpath "/extra/dir1:/extra/dir2" \
--transport http --port 8000
```
Environment variables honored: `PYTHON`, `MPLBACKEND=Agg` (default), `MCP_MAX_CONCURRENT_CELLS`, `MCP_MEMORY_BUDGET_MB`, `MCP_SOFT_WATERMARK`, `MCP_HARD_WATERMARK`.
## 📊 Datasets (DuckDB-backed)
Register CSV/Parquet files (or globs) as DuckDB views and query with SQL:
```python
# Register
await client.call_tool("notebook", {
"action": "datasets.register",
"dataset_name": "sales",
"paths": ["data/sales_*.parquet"],
"format": "parquet"
})
# Describe
await client.call_tool("notebook", {"action": "datasets.describe", "dataset_name": "sales"})
# Query (preview + full Parquet result on disk)
await client.call_tool("notebook", {
"action": "datasets.sql",
"query": "select date, sum(amount) as total from sales group by date order by date"
})
```
## 🔧 Configuration
### FastMCP Configuration (`fastmcp.json`)
```json
{
"$schema": "https://gofastmcp.com/public/schemas/fastmcp.json/v1.json",
"source": {
"type": "filesystem",
"path": "src/python_mcp_server/server.py",
"entrypoint": "mcp"
},
"environment": {
"type": "uv",
"python": ">=3.10",
"dependencies": [
"fastmcp>=1.0.0",
"jupyter_client>=8.0.0",
"matplotlib>=3.7.0",
"pandas>=2.0.0"
],
"editable": ["."]
},
"deployment": {
"transport": "stdio",
"log_level": "INFO",
"env": {
"MCP_WORKSPACE_DIR": "workspace",
"MPLBACKEND": "Agg",
"PYTHONUNBUFFERED": "1"
}
}
}
```
### Environment Variables
```bash
export MCP_WORKSPACE_DIR="./workspace" # Workspace directory
export MPLBACKEND="Agg" # Matplotlib backend
export PYTHONUNBUFFERED="1" # Unbuffered output
```
### Command Line Options
```bash
python-mcp-server \
--port 8000 \
--host 0.0.0.0 \
--workspace ./custom_workspace
```
## 📁 Workspace Structure
```
workspace/
├── scripts/ # Saved Python scripts
├── outputs/ # Generated files (plots, data, etc.)
├── uploads/ # Uploaded files via HTTP
└── (user files) # Any files created during execution
```
## 🤝 Integration Examples
### With Claude Desktop (STDIO Mode)
**Method 1: Direct Command**
```json
{
"mcpServers": {
"python-interpreter": {
"command": "python-mcp-server",
"args": ["--workspace", "/path/to/workspace"]
}
}
}
```
**Method 2: FastMCP CLI (Recommended)**
```bash
# Install for Claude Desktop
fastmcp install claude-desktop fastmcp.json --name "Python Interpreter"
```
This generates the correct configuration automatically.
**Method 3: Direct Python Path**
```json
{
"mcpServers": {
"python-interpreter": {
"command": "python",
"args": [
"/path/to/src/python_mcp_server/server.py",
"--workspace", "/path/to/workspace"
]
}
}
}
```
### With Claude Code
```bash
fastmcp install claude-code fastmcp.json --name "Python Interpreter"
```
### With Cursor
```bash
fastmcp install cursor fastmcp.json --name "Python Interpreter"
```
### Custom HTTP Client
```python
# Raw HTTP/JSON-RPC
import httpx
async def call_tool(tool_name, arguments):
async with httpx.AsyncClient() as client:
response = await client.post("http://localhost:8000/mcp", json={
"jsonrpc": "2.0",
"method": "tools/call",
"params": {"name": tool_name, "arguments": arguments},
"id": 1
})
return response.json()
```
### With uvx (No Installation)
```bash
# Run directly without installing globally
uvx python-mcp-server --port 8000
# With additional dependencies
uvx --with pandas --with numpy python-mcp-server --port 8000
```
## 🧪 Development
### Setup
```bash
git clone https://github.com/deadmeme5441/python-mcp-server.git
cd python-mcp-server
uv sync
```
### Testing
```bash
# Run all tests
uv run pytest tests/ -v
# Run specific test
uv run pytest tests/test_sessions.py -v
# With coverage
uv run pytest --cov=src --cov-report=html
```
### Code Quality
```bash
# Linting
uvx ruff@latest check .
# Type checking
uv run mypy src/
# Formatting
uvx ruff@latest format .
```
### FastMCP Development
```bash
# Run with FastMCP for development
fastmcp dev
# Test different transports
fastmcp run --transport http --port 8000
fastmcp run --transport stdio
```
## 📚 Documentation
- **[Complete Documentation](https://deadmeme5441.github.io/python-mcp-server/)** - Full guides and API reference
- **[Getting Started](https://deadmeme5441.github.io/python-mcp-server/getting-started/)** - Installation and first steps
- **[Architecture](https://deadmeme5441.github.io/python-mcp-server/architecture/)** - Technical deep dive
- **[Examples](https://deadmeme5441.github.io/python-mcp-server/examples/)** - Practical usage patterns
- **[Troubleshooting](https://deadmeme5441.github.io/python-mcp-server/troubleshooting/)** - Common issues and solutions
## 🔒 Security
- **Workspace Sandboxing**: All operations restricted to configured workspace
- **Path Validation**: Protection against directory traversal attacks
- **Resource Limits**: Configurable memory and CPU constraints
- **Process Isolation**: Each session runs in isolated Jupyter kernel
- **Input Sanitization**: All inputs validated via Pydantic models
## 🚀 Use Cases
- **AI Agent Environments**: Reliable Python execution for AI agents
- **Educational Platforms**: Safe, isolated code execution for learning
- **Data Analysis Workflows**: Session-based data processing pipelines
- **Research & Prototyping**: Quick iteration with state preservation
- **Jupyter Alternative**: MCP-native Python execution environment
- **Claude Desktop Integration**: Enhanced Python capabilities for Claude
## 📋 Changelog (v0.6.0)
### 🎉 Major Changes
- **New Package Structure**: Migrated to `src/python_mcp_server/` layout
- **FastMCP Integration**: Added native `fastmcp.json` configuration
- **Fixed CLI Command**: `python-mcp-server` now works correctly
- **Enhanced Installation**: Multiple installation methods supported
### 🔧 Improvements
- **Better Testing**: Fixed all test imports and module structure
- **Documentation**: Updated for new package structure
- **Claude Desktop**: Improved integration and configuration
- **Code Quality**: Full linting compliance and type checking
### 🐛 Bug Fixes
- **Entry Point**: Fixed package entry point configuration
- **Module Imports**: Resolved import issues in tests
- **Build System**: Proper hatchling configuration
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](https://deadmeme5441.github.io/python-mcp-server/development/) for details.
1. Fork the repository
2. Create your feature branch: `git checkout -b feature/amazing-feature`
3. Commit your changes: `git commit -m 'Add amazing feature'`
4. Push to the branch: `git push origin feature/amazing-feature`
5. Open a Pull Request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- **[FastMCP](https://github.com/jlowin/fastmcp)** - Excellent MCP framework
- **[Jupyter](https://jupyter.org/)** - Kernel architecture inspiration
- **[Model Context Protocol](https://modelcontextprotocol.io/)** - Protocol specification
- **[uv](https://docs.astral.sh/uv/)** - Fast Python package manager
## 🔗 Links
- **PyPI**: [python-mcp-server](https://pypi.org/project/python-mcp-server/)
- **Documentation**: [deadmeme5441.github.io/python-mcp-server](https://deadmeme5441.github.io/python-mcp-server/)
- **Issues**: [GitHub Issues](https://github.com/deadmeme5441/python-mcp-server/issues)
- **Discussions**: [GitHub Discussions](https://github.com/deadmeme5441/python-mcp-server/discussions)
---
<div align="center">
**[⭐ Star this repo](https://github.com/deadmeme5441/python-mcp-server) if you find it useful!**
Built with ❤️ by [DeadMeme5441](https://github.com/DeadMeme5441)
</div>
Raw data
{
"_id": null,
"home_page": null,
"name": "python-mcp-server",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "fastmcp, health-monitoring, jupyter, mcp, mcp-server, python-interpreter, session-management",
"author": null,
"author_email": "DeadMeme5441 <deadunderscorememe@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/7d/3b/3f3c95dfe06ea983ee42dafce634367c4a6b552768a324b88aecbfdc91a8/python_mcp_server-1.0.1.tar.gz",
"platform": null,
"description": "# Python Interpreter MCP Server\n\n[](https://github.com/deadmeme5441/python-mcp-server/actions)\n[](https://pypi.org/project/python-mcp-server/)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://deadmeme5441.github.io/python-mcp-server/)\n\nA world-class Python interpreter MCP (Model Context Protocol) server that provides secure, isolated Python code execution with advanced session management and health monitoring. Built with FastMCP for production-grade reliability.\n\n## \u2728 Features\n\n### \ud83d\ude80 **Production-Ready Architecture**\n- **FastMCP Middleware Stack**: Professional error handling, timing, and contextual logging\n- **Session-Based Isolation**: Multiple independent Python kernels with complete state separation \n- **Health Monitoring**: Real-time kernel diagnostics with intelligent restart capabilities\n- **Progressive Timeouts**: Resilient execution with smart retry logic\n\n### \ud83d\udd12 **Security & Reliability** \n- **Workspace Sandboxing**: Path traversal protection and secure file operations\n- **Resource Monitoring**: CPU, memory, and process health tracking\n- **State Preservation**: Automatic kernel state backup and restoration\n- **Error Resilience**: Graceful handling of kernel failures and timeouts\n\n### \ud83d\udee0 **Developer Experience**\n- **Notebook Surface**: One tool to run cells, manage datasets, and export artifacts\n- **File Management**: Read, write, delete operations with safety checks \n- **Package Installation**: Dynamic dependency management with uv/pip\n\n### \ud83c\udfaf **FastMCP Integration**\n- **Native FastMCP Configuration**: Built-in `fastmcp.json` for easy deployment\n- **CLI Integration**: Works seamlessly with FastMCP CLI commands\n- **Multiple Transport Modes**: STDIO, HTTP, Server-Sent Events support\n- **Claude Desktop Ready**: Perfect integration with Claude Desktop\n\n## \ud83d\ude80 Quick Start\n\n### Installation\n\n**Method 1: PyPI (Recommended)**\n```bash\npip install python-mcp-server\n```\n\n**Method 2: uvx (Isolated)**\n```bash\nuvx install python-mcp-server\n```\n\n**Method 3: FastMCP CLI (For Claude Desktop)**\n```bash\nfastmcp install claude-desktop python-mcp-server\n```\n\n### Basic Usage\n\n**Standalone Server (HTTP Mode)**\n```bash\n# Start HTTP server\npython-mcp-server --host 127.0.0.1 --port 8000\n\n# Custom workspace\npython-mcp-server --workspace /path/to/workspace --port 8000\n```\n\n**FastMCP CLI (Recommended)**\n```bash\n# Run with FastMCP (auto-detects fastmcp.json)\nfastmcp run\n\n# Run with specific transport\nfastmcp run --transport http --port 8000\n\n# For development/testing\nfastmcp dev\n```\n\n### Client Usage\n\n**FastMCP Client**\n```python\nimport asyncio\nfrom fastmcp.client import Client\n\nasync def main():\n async with Client(\"http://localhost:8000/mcp\") as client:\n # Execute Python code\n result = await client.call_tool(\"run_python_code\", {\n \"code\": \"\"\"\nimport numpy as np\nimport matplotlib.pyplot as plt\n\nx = np.linspace(0, 10, 100)\ny = np.sin(x)\n\nplt.figure(figsize=(10, 6))\nplt.plot(x, y, 'b-', linewidth=2)\nplt.title('Sine Wave')\nplt.grid(True)\nplt.show()\n\nprint(\"Plot created successfully!\")\n\"\"\"\n })\n print(\"Output:\", result.data[\"stdout\"])\n\nasyncio.run(main())\n```\n\n## \ud83c\udfd7 Architecture\n\n```mermaid\ngraph TB\n A[MCP Client] --> B[FastMCP Server]\n B --> C[Session Manager]\n C --> D[Kernel Session 1]\n C --> E[Kernel Session 2]\n C --> F[Default Session]\n \n B --> G[Health Monitor]\n G --> H[Resource Tracker]\n G --> I[Timeout Handler]\n \n B --> J[Workspace Manager]\n J --> K[File Operations]\n J --> L[Security Layer]\n```\n\n## \ud83d\udce6 Package Structure (v1.0.0)\n\n```\nsrc/python_mcp_server/\n\u251c\u2500\u2500 server.py # Main FastMCP server implementation\n\u251c\u2500\u2500 __init__.py # Package initialization\n\u2514\u2500\u2500 ...\n\nfastmcp.json # FastMCP configuration\npyproject.toml # Package metadata and dependencies\ntests/ # Comprehensive test suite\ndocs/ # Documentation source\n```\n\n## \ud83d\udd27 Tools Reference\n\n### Notebook (single surface)\n`notebook(action=..., ...)` \u2014 one tool for cells, datasets, and exports.\n\n- Actions:\n - `run` \u2014 execute a cell; capture stdout/stderr, figures (PNG/SVG), JSON outputs, and a workspace diff. Writes a manifest per cell under `outputs/notebooks/<id>/`.\n - `cells` \u2014 list executed cells (from index.json).\n - `cell` \u2014 fetch one cell\u2019s manifest.\n - `export` \u2014 write a `.ipynb` (and `.html` if available) to `outputs/notebooks/`.\n - `reset` \u2014 clear notebook manifests for the same `notebook_id` (kernel is not restarted).\n - `datasets.register` \u2014 create/update a DuckDB VIEW over CSV/Parquet files or globs.\n - `datasets.list` \u2014 show registered datasets.\n - `datasets.describe` \u2014 schema + head(50).\n - `datasets.drop` \u2014 remove a registered dataset/view.\n - `datasets.sql` \u2014 run SQL across registered views; returns preview and writes full result to Parquet.\n\n### Core Execution\n- `run_python_code` - Execute Python with output capture (rich display assets saved to `outputs/`)\n- `restart_kernel` - Clean kernel restart with optional state preservation\n\n### File Operations\n- `list_files` - Browse workspace (flat or tree view)\n- `read_file` / `write_file` / `delete_file` - Safe file operations\n\n### Package Management\n- `install_dependencies` - Dynamic dependency installation with uv/pip fallback\n\n## \ud83d\udca1 Advanced Usage\n\n### Notes\n- Session isolation, health and concurrency controls run under the hood; the public tool surface is intentionally minimal for agent reliability.\n\n## \ud83e\uddf0 Interpreter / Venv Configuration\n\nThe server runs the Jupyter kernel with the same interpreter and environment as the process by default. You can override with flags in both stdio and http modes:\n\n```bash\npython-mcp-server \\\n --python /path/to/python \\\n --venv /path/to/venv \\\n --pythonpath \"/extra/dir1:/extra/dir2\" \\\n --transport http --port 8000\n```\n\nEnvironment variables honored: `PYTHON`, `MPLBACKEND=Agg` (default), `MCP_MAX_CONCURRENT_CELLS`, `MCP_MEMORY_BUDGET_MB`, `MCP_SOFT_WATERMARK`, `MCP_HARD_WATERMARK`.\n\n## \ud83d\udcca Datasets (DuckDB-backed)\n\nRegister CSV/Parquet files (or globs) as DuckDB views and query with SQL:\n\n```python\n# Register\nawait client.call_tool(\"notebook\", {\n \"action\": \"datasets.register\",\n \"dataset_name\": \"sales\",\n \"paths\": [\"data/sales_*.parquet\"],\n \"format\": \"parquet\"\n})\n\n# Describe\nawait client.call_tool(\"notebook\", {\"action\": \"datasets.describe\", \"dataset_name\": \"sales\"})\n\n# Query (preview + full Parquet result on disk)\nawait client.call_tool(\"notebook\", {\n \"action\": \"datasets.sql\",\n \"query\": \"select date, sum(amount) as total from sales group by date order by date\"\n})\n```\n\n## \ud83d\udd27 Configuration\n\n### FastMCP Configuration (`fastmcp.json`)\n```json\n{\n \"$schema\": \"https://gofastmcp.com/public/schemas/fastmcp.json/v1.json\",\n \"source\": {\n \"type\": \"filesystem\",\n \"path\": \"src/python_mcp_server/server.py\",\n \"entrypoint\": \"mcp\"\n },\n \"environment\": {\n \"type\": \"uv\",\n \"python\": \">=3.10\",\n \"dependencies\": [\n \"fastmcp>=1.0.0\",\n \"jupyter_client>=8.0.0\",\n \"matplotlib>=3.7.0\",\n \"pandas>=2.0.0\"\n ],\n \"editable\": [\".\"]\n },\n \"deployment\": {\n \"transport\": \"stdio\",\n \"log_level\": \"INFO\",\n \"env\": {\n \"MCP_WORKSPACE_DIR\": \"workspace\",\n \"MPLBACKEND\": \"Agg\",\n \"PYTHONUNBUFFERED\": \"1\"\n }\n }\n}\n```\n\n### Environment Variables\n```bash\nexport MCP_WORKSPACE_DIR=\"./workspace\" # Workspace directory\nexport MPLBACKEND=\"Agg\" # Matplotlib backend\nexport PYTHONUNBUFFERED=\"1\" # Unbuffered output\n```\n\n### Command Line Options\n```bash\npython-mcp-server \\\n --port 8000 \\\n --host 0.0.0.0 \\\n --workspace ./custom_workspace\n```\n\n## \ud83d\udcc1 Workspace Structure\n\n```\nworkspace/\n\u251c\u2500\u2500 scripts/ # Saved Python scripts\n\u251c\u2500\u2500 outputs/ # Generated files (plots, data, etc.)\n\u251c\u2500\u2500 uploads/ # Uploaded files via HTTP\n\u2514\u2500\u2500 (user files) # Any files created during execution\n```\n\n## \ud83e\udd1d Integration Examples\n\n### With Claude Desktop (STDIO Mode)\n\n**Method 1: Direct Command**\n```json\n{\n \"mcpServers\": {\n \"python-interpreter\": {\n \"command\": \"python-mcp-server\",\n \"args\": [\"--workspace\", \"/path/to/workspace\"]\n }\n }\n}\n```\n\n**Method 2: FastMCP CLI (Recommended)**\n```bash\n# Install for Claude Desktop\nfastmcp install claude-desktop fastmcp.json --name \"Python Interpreter\"\n```\n\nThis generates the correct configuration automatically.\n\n**Method 3: Direct Python Path**\n```json\n{\n \"mcpServers\": {\n \"python-interpreter\": {\n \"command\": \"python\", \n \"args\": [\n \"/path/to/src/python_mcp_server/server.py\",\n \"--workspace\", \"/path/to/workspace\"\n ]\n }\n }\n}\n```\n\n### With Claude Code\n```bash\nfastmcp install claude-code fastmcp.json --name \"Python Interpreter\"\n```\n\n### With Cursor\n```bash\nfastmcp install cursor fastmcp.json --name \"Python Interpreter\"\n```\n\n### Custom HTTP Client\n```python\n# Raw HTTP/JSON-RPC\nimport httpx\n\nasync def call_tool(tool_name, arguments):\n async with httpx.AsyncClient() as client:\n response = await client.post(\"http://localhost:8000/mcp\", json={\n \"jsonrpc\": \"2.0\",\n \"method\": \"tools/call\",\n \"params\": {\"name\": tool_name, \"arguments\": arguments},\n \"id\": 1\n })\n return response.json()\n```\n\n### With uvx (No Installation)\n```bash\n# Run directly without installing globally\nuvx python-mcp-server --port 8000\n\n# With additional dependencies\nuvx --with pandas --with numpy python-mcp-server --port 8000\n```\n\n## \ud83e\uddea Development\n\n### Setup\n```bash\ngit clone https://github.com/deadmeme5441/python-mcp-server.git\ncd python-mcp-server\nuv sync\n```\n\n### Testing\n```bash\n# Run all tests\nuv run pytest tests/ -v\n\n# Run specific test\nuv run pytest tests/test_sessions.py -v\n\n# With coverage\nuv run pytest --cov=src --cov-report=html\n```\n\n### Code Quality\n```bash\n# Linting\nuvx ruff@latest check .\n\n# Type checking\nuv run mypy src/\n\n# Formatting\nuvx ruff@latest format .\n```\n\n### FastMCP Development\n```bash\n# Run with FastMCP for development\nfastmcp dev\n\n# Test different transports\nfastmcp run --transport http --port 8000\nfastmcp run --transport stdio\n```\n\n## \ud83d\udcda Documentation\n\n- **[Complete Documentation](https://deadmeme5441.github.io/python-mcp-server/)** - Full guides and API reference\n- **[Getting Started](https://deadmeme5441.github.io/python-mcp-server/getting-started/)** - Installation and first steps\n- **[Architecture](https://deadmeme5441.github.io/python-mcp-server/architecture/)** - Technical deep dive\n- **[Examples](https://deadmeme5441.github.io/python-mcp-server/examples/)** - Practical usage patterns\n- **[Troubleshooting](https://deadmeme5441.github.io/python-mcp-server/troubleshooting/)** - Common issues and solutions\n\n## \ud83d\udd12 Security\n\n- **Workspace Sandboxing**: All operations restricted to configured workspace\n- **Path Validation**: Protection against directory traversal attacks \n- **Resource Limits**: Configurable memory and CPU constraints\n- **Process Isolation**: Each session runs in isolated Jupyter kernel\n- **Input Sanitization**: All inputs validated via Pydantic models\n\n## \ud83d\ude80 Use Cases\n\n- **AI Agent Environments**: Reliable Python execution for AI agents\n- **Educational Platforms**: Safe, isolated code execution for learning\n- **Data Analysis Workflows**: Session-based data processing pipelines \n- **Research & Prototyping**: Quick iteration with state preservation\n- **Jupyter Alternative**: MCP-native Python execution environment\n- **Claude Desktop Integration**: Enhanced Python capabilities for Claude\n\n## \ud83d\udccb Changelog (v0.6.0)\n\n### \ud83c\udf89 Major Changes\n- **New Package Structure**: Migrated to `src/python_mcp_server/` layout\n- **FastMCP Integration**: Added native `fastmcp.json` configuration\n- **Fixed CLI Command**: `python-mcp-server` now works correctly\n- **Enhanced Installation**: Multiple installation methods supported\n\n### \ud83d\udd27 Improvements\n- **Better Testing**: Fixed all test imports and module structure\n- **Documentation**: Updated for new package structure\n- **Claude Desktop**: Improved integration and configuration\n- **Code Quality**: Full linting compliance and type checking\n\n### \ud83d\udc1b Bug Fixes\n- **Entry Point**: Fixed package entry point configuration\n- **Module Imports**: Resolved import issues in tests\n- **Build System**: Proper hatchling configuration\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](https://deadmeme5441.github.io/python-mcp-server/development/) for details.\n\n1. Fork the repository\n2. Create your feature branch: `git checkout -b feature/amazing-feature`\n3. Commit your changes: `git commit -m 'Add amazing feature'`\n4. Push to the branch: `git push origin feature/amazing-feature`\n5. Open a Pull Request\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- **[FastMCP](https://github.com/jlowin/fastmcp)** - Excellent MCP framework\n- **[Jupyter](https://jupyter.org/)** - Kernel architecture inspiration\n- **[Model Context Protocol](https://modelcontextprotocol.io/)** - Protocol specification\n- **[uv](https://docs.astral.sh/uv/)** - Fast Python package manager\n\n## \ud83d\udd17 Links\n\n- **PyPI**: [python-mcp-server](https://pypi.org/project/python-mcp-server/)\n- **Documentation**: [deadmeme5441.github.io/python-mcp-server](https://deadmeme5441.github.io/python-mcp-server/)\n- **Issues**: [GitHub Issues](https://github.com/deadmeme5441/python-mcp-server/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/deadmeme5441/python-mcp-server/discussions)\n\n---\n\n<div align=\"center\">\n\n**[\u2b50 Star this repo](https://github.com/deadmeme5441/python-mcp-server) if you find it useful!**\n\nBuilt with \u2764\ufe0f by [DeadMeme5441](https://github.com/DeadMeme5441)\n\n</div>\n",
"bugtrack_url": null,
"license": null,
"summary": "A world-class Python interpreter MCP server with session management, health monitoring, and FastMCP middleware",
"version": "1.0.1",
"project_urls": {
"Changelog": "https://github.com/deadmeme5441/python-mcp-server/blob/main/CHANGELOG.md",
"Documentation": "https://deadmeme5441.github.io/python-mcp-server/",
"Homepage": "https://deadmeme5441.github.io/python-mcp-server/",
"Issues": "https://github.com/deadmeme5441/python-mcp-server/issues",
"Repository": "https://github.com/deadmeme5441/python-mcp-server"
},
"split_keywords": [
"fastmcp",
" health-monitoring",
" jupyter",
" mcp",
" mcp-server",
" python-interpreter",
" session-management"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "81515ad4e7153b3c9cfd8b6fbcf1e6009f3cfca66dd71b0651e761aa6d198c52",
"md5": "acfed1ca389bda1cf254e000ede1fc39",
"sha256": "70c47c24500a6955f0435ab5d67c16e3683d6eb6b75133d1191f82ae1bec8536"
},
"downloads": -1,
"filename": "python_mcp_server-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "acfed1ca389bda1cf254e000ede1fc39",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 23104,
"upload_time": "2025-09-10T13:38:06",
"upload_time_iso_8601": "2025-09-10T13:38:06.640670Z",
"url": "https://files.pythonhosted.org/packages/81/51/5ad4e7153b3c9cfd8b6fbcf1e6009f3cfca66dd71b0651e761aa6d198c52/python_mcp_server-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "7d3b3f3c95dfe06ea983ee42dafce634367c4a6b552768a324b88aecbfdc91a8",
"md5": "c2e615d5d8c3366c9cce069baaf8eb37",
"sha256": "5a6efcf1867090e0f8a5b023b7a7c0fc8bb4e56fe792ccecb574ad2817cc7a2c"
},
"downloads": -1,
"filename": "python_mcp_server-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "c2e615d5d8c3366c9cce069baaf8eb37",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 245665,
"upload_time": "2025-09-10T13:38:07",
"upload_time_iso_8601": "2025-09-10T13:38:07.949990Z",
"url": "https://files.pythonhosted.org/packages/7d/3b/3f3c95dfe06ea983ee42dafce634367c4a6b552768a324b88aecbfdc91a8/python_mcp_server-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-10 13:38:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "deadmeme5441",
"github_project": "python-mcp-server",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "python-mcp-server"
}
JSON
