mcp-forge/README.md

MCP-Forge

Secure Python Execution Server with Model Context Protocol (MCP) Support

MCP-Forge provides a secure, containerized Python execution environment that integrates with the Model Context Protocol. It enables AI assistants and other MCP clients to execute Python code safely with resource limits, security controls, and audit logging.

Features

• 🔒 Secure Execution: Podman-based container isolation with resource limits
• 🎯 MCP Protocol: Native integration with Model Context Protocol for AI assistants
• 📊 Dual Backends:
  • Simple backend for stateless code execution
  • Jupyter backend for stateful sessions with kernel persistence
• 🛡️ Security Controls:
  • Package allowlist/blocklist validation
  • Resource limits (memory, CPU, timeout, storage)
  • Comprehensive audit logging
• 🔧 Environment Building: Dynamic Python environment creation with uv
• 🌉 MCP Bridge: Connect to external MCP tool servers (stdio, HTTP, SSE)
  • Support for stdio-based MCP servers (command-line tools)
  • HTTP transport for REST API-based MCP servers
  • SSE transport for Server-Sent Events MCP servers

Quick Start

Installation

git clone <repository>
cd mcp-forge
uv sync

Configuration

1. Copy example configuration:

cp config.example.yaml config.yaml

2. Update Podman socket path in config.yaml:

server:
  podman_socket: /run/user/1000/podman/podman.sock

3. Start Podman socket:

systemctl --user start podman.socket

Running the Server

# stdio transport (for MCP clients)
uv run mcp-forge --config config.yaml

# HTTP transport (REST API)
uv run mcp-forge --config config.yaml --transport http --port 8011

# SSE transport (Server-Sent Events)
uv run mcp-forge --config config.yaml --transport sse --port 8080

# Alternative: using Python module
uv run python -m mcp_forge --config config.yaml --transport http --port 8011

CLI Options

--config PATH        Path to configuration file (required)
--host HOST          Server host address (default: localhost)
--port PORT          Server port (default: 3000)
--transport TYPE     Transport protocol: stdio or sse (default: stdio)
--verbose, -v        Enable verbose logging

MCP Client Integration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "mcp-forge": {
      "command": "uv",
      "args": ["run", "mcp-forge", "--config", "/absolute/path/to/config.yaml"]
    }
  }
}

Available MCP Tools

execute_python

Execute Python code in isolated container:

{
  "code": "print(2 + 2)",
  "timeout": 30,
  "memory": "512m"
}

build_environment

Create custom Python environment with packages:

{
  "python_version": "3.11",
  "packages": ["requests", "pandas"]
}

document_state

Manage Jupyter session state:

{
  "session_id": "user_session",
  "code": "x = 42",
  "clear": false
}

Architecture

┌─────────────────┐
│   MCP Client    │
│ (Claude/Other)  │
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│  MCP-Forge      │
│   Server        │
├─────────────────┤
│ • Tool Handlers │
│ • MCP Bridge    │
│ • Security      │
│ • Audit Logger  │
└────────┬────────┘
         │
         ↓
┌─────────────────┐
│    Podman       │
│   Containers    │
├─────────────────┤
│ • Python 3.11   │
│ • Python 3.12   │
│ • Jupyter       │
└─────────────────┘

Security

• Container Isolation: Each execution runs in isolated Podman container
• Resource Limits: Memory, CPU, timeout, and storage quotas enforced
• Package Validation: Allowlist/blocklist for package installation
• Audit Logging: All operations logged with timestamps and metadata
• Network Restrictions: Containers run without network access by default

Testing

# Run all tests
uv run pytest

# Run specific test suite
uv run pytest tests/server/ -v

# Integration tests (requires Podman)
uv run pytest tests/integration/ -v

Test Status: 388 tests passing, 27 integration tests pending Phase 5.4

Configuration Reference

See config.example.yaml for complete configuration options.

Key sections:

• server: Host, port, Podman socket
• security: Audit log, resource enforcement
• execution: Timeouts, memory limits, backends
• images: Container image configuration
• sessions: Jupyter session management
• environment_builder: Package validation, caching

Development

Project Structure

mcp-forge/
├── src/mcp_forge/
│   ├── server/          # MCP server implementation
│   ├── config/          # Configuration schemas
│   ├── security/        # Security & audit
│   ├── podman/          # Container management
│   ├── execution/       # Execution backends
│   ├── builder/         # Environment building
│   └── mcp/             # MCP protocol integration
├── tests/               # Test suite
├── config/              # Default configurations
└── docs/                # Documentation

Running Tests

# Unit tests
uv run pytest tests/ -v

# With coverage
uv run pytest --cov=mcp_forge --cov-report=html

# Specific module
uv run pytest tests/execution/ -v

Troubleshooting

Podman Socket Not Found

systemctl --user status podman.socket
systemctl --user start podman.socket

Permission Denied

Check socket permissions:

ls -l /run/user/$(id -u)/podman/podman.sock

Container Images

Pull and tag images:

podman pull python:3.11-slim
podman tag python:3.11-slim mcp-forge/python:3.11

License

[Add license information]

Contributing

[Add contribution guidelines]

Documentation

• Quick Start Guide
• HTTP Transport Configuration
• Project Status
• Architecture Overview
• Development TODO