{"id":48237180,"url":"https://github.com/madhanmohanreddy2301/codeboxmcp","last_synced_at":"2026-04-04T20:02:30.651Z","repository":{"id":344442395,"uuid":"1181841116","full_name":"MadhanMohanReddy2301/CodeBoxMCP","owner":"MadhanMohanReddy2301","description":"Code Box is a self-hosted, open-source Model Context Protocol (MCP) server that provides AI agents with a secure, stateful environment to execute Python and JavaScript code. It acts as a direct, zero-cost replacement for Azure Assistants Code Interpreter by persisting variables across calls, and safely executing read-only SQL querys","archived":false,"fork":false,"pushed_at":"2026-03-14T17:50:31.000Z","size":124,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-15T03:57:43.513Z","etag":null,"topics":["agentic-ai","code-interpreter","mcp-server","open-interpreter","sql","storage"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MadhanMohanReddy2301.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-14T17:41:04.000Z","updated_at":"2026-03-14T17:54:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MadhanMohanReddy2301/CodeBoxMCP","commit_stats":null,"previous_names":["madhanmohanreddy2301/codeboxmcp"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/MadhanMohanReddy2301/CodeBoxMCP","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadhanMohanReddy2301%2FCodeBoxMCP","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadhanMohanReddy2301%2FCodeBoxMCP/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadhanMohanReddy2301%2FCodeBoxMCP/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadhanMohanReddy2301%2FCodeBoxMCP/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MadhanMohanReddy2301","download_url":"https://codeload.github.com/MadhanMohanReddy2301/CodeBoxMCP/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MadhanMohanReddy2301%2FCodeBoxMCP/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31411672,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T19:29:44.979Z","status":"ssl_error","status_checked_at":"2026-04-04T19:29:11.535Z","response_time":60,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-ai","code-interpreter","mcp-server","open-interpreter","sql","storage"],"created_at":"2026-04-04T20:02:25.505Z","updated_at":"2026-04-04T20:02:30.639Z","avatar_url":"https://github.com/MadhanMohanReddy2301.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\r\n  \u003ch1 align=\"center\"\u003e📦 Code Box\u003c/h1\u003e\r\n  \u003cp align=\"center\"\u003e\r\n    \u003cstrong\u003eA self-hosted, open replacement for Azure Assistants Code Interpreter\u003c/strong\u003e\u003cbr\u003e\r\n    Stateful code execution as an MCP server — own your runtime, skip the per-token cost.\r\n  \u003c/p\u003e\r\n  \u003cp align=\"center\"\u003e\r\n    \u003cimg src=\"https://img.shields.io/badge/version-1.0.0-blue\" alt=\"Version\"\u003e\r\n    \u003cimg src=\"https://img.shields.io/badge/python-3.10%2B-brightgreen\" alt=\"Python 3.10+\"\u003e\r\n    \u003cimg src=\"https://img.shields.io/badge/transport-Streamable%20HTTP-orange\" alt=\"Transport\"\u003e\r\n    \u003cimg src=\"https://img.shields.io/badge/license-Proprietary-red\" alt=\"License\"\u003e\r\n  \u003c/p\u003e\r\n\u003c/p\u003e\r\n\r\n⭐ **If you find this project useful, please consider giving it a star!** ⭐\r\n\r\n---\r\n\r\n## Overview\r\n\r\n**Code Box** is a self-hosted, production-grade replacement for [Azure Assistants Code Interpreter](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/code-interpreter). It delivers the same stateful code execution experience — persistent kernels, file I/O, artifact generation — without being locked into the Azure OpenAI Assistants API or paying per-token execution costs.\r\n\r\nBuilt on [Open Interpreter](https://github.com/OpenInterpreter/open-interpreter) and exposed via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io), Code Box runs on **any infrastructure** (your laptop, a VM, Azure Web App, a container) and plugs into **any MCP-compatible agent framework**: Semantic Kernel, LangGraph, CrewAI, AutoGen, or your own custom client.\r\n\r\n### Why Code Box over Azure Code Interpreter?\r\n\r\n| | Azure Code Interpreter | Code Box |\r\n|---|---|---|\r\n| **Hosting** | Managed by Azure OpenAI — no control | Self-hosted anywhere — full control |\r\n| **Cost** | Per-token + per-session charges | Zero marginal cost — run on your own compute |\r\n| **LLM coupling** | Tightly bound to Azure OpenAI models | **No LLM at the server** — bring any model, any provider |\r\n| **Framework lock-in** | Assistants API only | Open MCP protocol — works with any agent framework |\r\n| **SQL queries** | Not supported | Built-in `exec_sql` with two-level read-only safety |\r\n| **Artifact storage** | Azure-managed, opaque | Transparent local filesystem + optional Azure Blob with SAS URLs |\r\n| **Customisation** | Limited to API parameters | Full control over timeouts, file limits, session lifecycle, blob config |\r\n| **Multi-tenant isolation** | Per-assistant | Per-session — each session gets its own interpreter process and filesystem |\r\n\r\n### Key Capabilities\r\n\r\n| Capability | Description |\r\n|---|---|\r\n| **Stateful Code Execution** | Run Python/JS code across multiple calls; variables, imports, and DataFrames persist within a session. |\r\n| **SQL Query Execution** | Run read-only `SELECT` queries against Azure SQL with two-level safety (keyword blocking + always-rollback). |\r\n| **File Upload \u0026 Download** | Download files from URLs into isolated session workspaces for processing. |\r\n| **Artifact Management** | Auto-detect generated files (plots, CSVs, Excel, HTML, PDF, SVG, JSON) and surface them to the agent. |\r\n| **Azure Blob Integration** | Auto-upload artifacts to Azure Blob Storage with time-limited SAS URLs. |\r\n| **Multi-Tenant Isolation** | Each session gets its own interpreter process, filesystem, and lifecycle. |\r\n\r\n---\r\n\r\n## Architecture\r\n\r\n\u003cp align=\"center\"\u003e\r\n  \u003cimg src=\"CodeBox.png\" alt=\"Code Box Architecture\" width=\"800\"\u003e\r\n\u003c/p\u003e\r\n\r\n### Design Principles\r\n\r\n- **One interpreter per session** — complete isolation; no state bleeds across sessions.\r\n- **Zero LLM dependency** — the server executes code directly via Open Interpreter's runtime. Your agent chooses the model; Code Box just runs the code.\r\n- **Stateless HTTP transport** — every request is independent, making it fully compatible with Azure Web App reverse proxies, load balancers, and containers.\r\n- **Client config clamping** — `effective = min(client_value, server_max)` ensures server-configured safety limits can never be exceeded by any client.\r\n\r\n---\r\n\r\n## Prerequisites\r\n\r\n| Requirement | Details |\r\n|---|---|\r\n| **Python** | 3.10 or higher |\r\n| **pip** | Latest version recommended |\r\n| **ODBC Driver** *(if using `exec_sql`)* | Microsoft ODBC Driver 17+ for SQL Server |\r\n| **Azure Blob Storage** *(optional)* | Storage account + connection string for artifact uploads |\r\n| **Azure SQL Database** *(optional)* | Database + connection string for `exec_sql` |\r\n\r\n---\r\n\r\n## Quick Start\r\n\r\n### 1. Clone \u0026 set up the environment\r\n\r\n```bash\r\ncd CodeBoxMCP\r\n\r\n# Create and activate a virtual environment\r\npython -m venv .venv\r\n\r\n# Windows\r\n.venv\\Scripts\\activate\r\n\r\n# Linux / macOS\r\nsource .venv/bin/activate\r\n\r\n# Install dependencies\r\npip install -r requirements.txt\r\n```\r\n\r\n### 2. Configure environment variables\r\n\r\nCreate a `.env` file in the project root:\r\n\r\n```dotenv\r\n# ─── Server ───\r\nMCP_SERVER_NAME=Code Interpreter MCP\r\nMCP_HOST=0.0.0.0\r\nMCP_PORT=8000\r\n\r\n# ─── Session Lifecycle ───\r\nSESSION_TTL=3600\r\nIDLE_TIMEOUT=1800\r\nEXEC_TIMEOUT=300\r\n\r\n# ─── Azure Blob Storage (optional) ───\r\nAZURE_BLOB_CONNECTION_STRING=\u003cyour-connection-string\u003e\r\nAZURE_BLOB_CONTAINER_NAME=code-interpreter-artifacts\r\nBLOB_SAS_EXPIRY_HOURS=24\r\n\r\n# ─── Azure SQL Database (optional) ───\r\nAZURE_DATABASE_CONNECTION_STRING=\u003cyour-odbc-connection-string\u003e\r\nAZURE_DATABASE_PASSWORD=\u003cyour-password\u003e\r\n```\r\n\r\n### 3. Start the server\r\n\r\n```bash\r\n# Option A — module\r\npython -m codebox\r\n\r\n# Option B — script\r\npython server.py\r\n\r\n# Option C — shell (Linux/macOS)\r\nbash run.sh\r\n```\r\n\r\nOn success the server logs:\r\n\r\n```\r\n============================================================\r\n  Code Interpreter MCP\r\n  Transport : streamable-http\r\n  Endpoint  : http://localhost:8000/mcp\r\n============================================================\r\n```\r\n\r\n---\r\n\r\n## MCP Tools Reference\r\n\r\nCode Box exposes **7 tools** via MCP. All accept and return JSON.\r\n\r\n| Tool | Purpose |\r\n|---|---|\r\n| [`exec_code`](#exec_code) | Run Python/JS in a **stateful** kernel — variables persist across calls |\r\n| [`exec_sql`](#exec_sql) | Run **read-only SELECT** queries against Azure SQL |\r\n| [`upload_file`](#upload_file) | Download a file from a URL into the session's `input/` folder |\r\n| [`list_artifacts`](#list_artifacts) | List all generated files in `output/` |\r\n| [`session_info`](#session_info) | Get session paths (`input_dir`, `output_dir`) and effective config |\r\n| [`list_sessions`](#list_sessions) | Show all active sessions |\r\n| [`destroy_session`](#destroy_session) | Kill a session and free resources |\r\n\r\n### `exec_code`\r\n\r\nExecute code in a stateful interpreter session. State **persists** within the same `session_id` — variables, imports, DataFrames all survive across calls. Don't re-import or re-load what's already in memory; reference existing variables directly.\r\n\r\n```\r\nParameters:\r\n  session_id  (string, required)  — Unique session identifier; auto-created on first use.\r\n  language    (string, required)  — e.g. \"python\"\r\n  code        (string, required)  — The code to execute.\r\n```\r\n\r\nGenerated files (plots, CSVs, etc.) are automatically detected as artifacts. If Azure Blob is configured, each artifact gets a **SAS URL** in the response (`new_artifacts[].sas_url`).\r\n\r\n### `exec_sql`\r\n\r\nRun a read-only SQL query with **two-level safety**:\r\n\r\n1. **Application layer** — keyword blocking (rejects `INSERT`, `UPDATE`, `DELETE`, `DROP`, etc.).\r\n2. **Database layer** — always-rollback transaction; no writes can ever persist.\r\n\r\n**Small results** (≤ `SQL_MAX_INLINE_ROWS`, default 30) are returned inline as JSON. **Large results** are saved as CSV in `input/` — load directly with `pd.read_csv(path)`, no re-upload needed.\r\n\r\n### `upload_file`\r\n\r\nDownload a file from a URL (public or SAS) into the session's `input/` folder. Use the returned `saved_path` in subsequent `exec_code` calls. Respects `MAX_DOWNLOAD_SIZE` (default 500 MB) and `DOWNLOAD_TIMEOUT` (default 120 s).\r\n\r\n### `list_artifacts`\r\n\r\nReturns metadata for every artifact in the session's `output/` directory (filename, path, extension, size, optional SAS URL).\r\n\r\n### `session_info`\r\n\r\nReturns the session's working directory paths (`workdir`, `input_dir`, `output_dir`) and effective configuration. **Recommended as the first call** so the agent discovers absolute paths before writing or reading files.\r\n\r\n### `list_sessions`\r\n\r\nReturns all active sessions with `age_seconds`, `idle_seconds`, and `workdir`.\r\n\r\n### `destroy_session`\r\n\r\nExplicitly destroys a session — kills the interpreter process and deletes all session files. Call this when the agent is done to release resources.\r\n\r\n---\r\n\r\n## Session Lifecycle\r\n\r\nSessions are **auto-created** on first use — just pass any `session_id` and go. No explicit \"create\" step required.\r\n\r\n```\r\nFirst call with session_id          Subsequent calls (same ID)\r\n         │                                    │\r\n         ▼                                    ▼\r\n  ┌──────────────┐                   ┌──────────────┐\r\n  │ Auto-Create  │                   │ Reuse Session│\r\n  │ • New kernel │                   │ • State kept │\r\n  │ • Filesystem │                   │ • Timer reset│\r\n  └──────────────┘                   └──────────────┘\r\n         │                                    │\r\n         └──────── Expires or Destroyed ──────┘\r\n                          │\r\n                          ▼\r\n                  ┌──────────────┐\r\n                  │   Cleaned Up │\r\n                  │ • Process killed │\r\n                  │ • Files deleted  │\r\n                  └──────────────┘\r\n```\r\n\r\n- **TTL \u0026 idle timeout** — sessions expire after `SESSION_TTL` seconds total or `IDLE_TIMEOUT` seconds of inactivity.\r\n- **Cleanup loop** — a background thread reaps expired sessions every `CLEANUP_INTERVAL` seconds.\r\n- **Session recovery** — if a session is not found (expired/cleaned up), create a new one with the same `session_id` and re-upload files / re-run setup. Do not assume prior state survived.\r\n\r\n---\r\n\r\n## Best Practices\r\n\r\n1. **First call**: `session_info` to discover absolute paths, then import libraries + load data.\r\n2. **Next calls**: reuse variables already in memory — don't re-import or re-load.\r\n3. **Save outputs** to `output/` using absolute paths — they become artifacts automatically.\r\n4. **Check `new_artifacts`** in `exec_code` responses for file paths and SAS URLs.\r\n5. **Use `exec_sql`** for SQL queries — results land directly in the session, no extra code needed.\r\n6. **On error**, fix only the broken line — don't re-run everything from scratch.\r\n7. **Call `destroy_session`** when done to free interpreter processes and disk space.\r\n\r\n---\r\n\r\n## Client HTTP Headers\r\n\r\nClients can override server defaults on a per-request basis via HTTP headers. Values are **clamped** against server maximums.\r\n\r\n| Header | Overrides |\r\n|---|---|\r\n| `X-Session-Ttl` | `SESSION_TTL` |\r\n| `X-Idle-Timeout` | `IDLE_TIMEOUT` |\r\n| `X-Exec-Timeout` | `EXEC_TIMEOUT` |\r\n| `X-Download-Timeout` | `DOWNLOAD_TIMEOUT` |\r\n| `X-Max-Download-Size` | `MAX_DOWNLOAD_SIZE` |\r\n| `X-Blob-Connection-String` | Azure Blob connection string |\r\n| `X-Blob-Container-Name` | Azure Blob container name |\r\n| `X-Blob-Sas-Expiry-Hours` | SAS URL expiry |\r\n| `X-Db-Connection-String` | Azure SQL connection string |\r\n| `X-Db-Password` | Azure SQL password |\r\n\r\n---\r\n\r\n## Connecting from Agent Frameworks\r\n\r\nCode Box works with **any MCP-compatible client**. Here are quick-start snippets for popular frameworks:\r\n\r\n### Semantic Kernel (Python)\r\n\r\n```python\r\nfrom semantic_kernel.connectors.mcp import MCPStreamableHttpPlugin\r\n\r\nplugin = MCPStreamableHttpPlugin(\r\n    name=\"code_box\",\r\n    url=\"http://localhost:8000/mcp\",\r\n)\r\nkernel.add_plugin(plugin)\r\n```\r\n\r\n### LangGraph / LangChain\r\n\r\n```python\r\nfrom langchain_mcp_adapters.client import MultiServerMCPClient\r\n\r\nasync with MultiServerMCPClient({\r\n    \"code_box\": {\r\n        \"url\": \"http://localhost:8000/mcp\",\r\n        \"transport\": \"streamable_http\",\r\n    }\r\n}) as client:\r\n    tools = client.get_tools()\r\n```\r\n\r\n### CrewAI\r\n\r\n```python\r\nfrom crewai import Agent\r\nfrom crewai_tools import MCPServerAdapter\r\n\r\nwith MCPServerAdapter(\r\n    server_params={\"url\": \"http://localhost:8000/mcp\", \"transport\": \"streamable_http\"}\r\n) as tools:\r\n    agent = Agent(role=\"analyst\", tools=tools.tools)\r\n```\r\n\r\n### AutoGen\r\n\r\n```python\r\nfrom autogen_ext.tools.mcp import SseServerParams, mcp_server_tools\r\n\r\ntools = await mcp_server_tools(SseServerParams(url=\"http://localhost:8000/mcp\"))\r\nagent = AssistantAgent(\"analyst\", tools=tools)\r\n```\r\n\r\n---\r\n\r\n## Project Structure\r\n\r\n```\r\nCodeBoxMCP/\r\n├── server.py                  # Thin launcher (delegates to codebox.server)\r\n├── run.sh                     # Shell launcher (Linux/macOS)\r\n├── requirements.txt           # Python dependencies\r\n├── .env                       # Environment configuration (create this)\r\n├── DOCUMENTATION.md           # Full integration \u0026 usage guide\r\n├── USAGE_GUIDE.html           # HTML usage guide\r\n├── architecture.drawio        # Architecture diagram (draw.io)\r\n├── codebox/\r\n│   ├── __init__.py            # Package metadata \u0026 version\r\n│   ├── __main__.py            # `python -m codebox` entry point\r\n│   ├── config.py              # Centralised configuration (env vars)\r\n│   ├── server.py              # FastMCP server, tool definitions, entrypoint\r\n│   ├── session_manager.py     # Session lifecycle \u0026 interpreter management\r\n│   ├── db_manager.py          # Azure SQL query execution \u0026 safety\r\n│   ├── helpers.py             # Blob storage, artifact detection, downloads\r\n│   └── resources.py           # Embedded usage guide resource\r\n└── sessions/                  # Runtime session filesystems (auto-created)\r\n```\r\n\r\n---\r\n\r\n## Configuration Reference\r\n\r\nAll settings are configurable via environment variables or a `.env` file.\r\n\r\n| Variable | Default | Description |\r\n|---|---|---|\r\n| `MCP_SERVER_NAME` | `Code Interpreter MCP` | Server display name |\r\n| `MCP_HOST` | `0.0.0.0` | Bind address |\r\n| `PORT` / `MCP_PORT` | `8000` | Listening port |\r\n| `MCP_TRANSPORT` | `streamable-http` | Transport protocol |\r\n| `SESSION_TTL` | `3600` (1h) | Max session lifetime (seconds) |\r\n| `IDLE_TIMEOUT` | `1800` (30m) | Max idle time before cleanup (seconds) |\r\n| `CLEANUP_INTERVAL` | `60` | Cleanup loop interval (seconds) |\r\n| `EXEC_TIMEOUT` | `300` (5m) | Max code execution time per call (seconds) |\r\n| `DOWNLOAD_TIMEOUT` | `120` | Max file download time (seconds) |\r\n| `MAX_DOWNLOAD_SIZE` | `524288000` (500 MB) | Max downloadable file size (bytes) |\r\n| `SQL_MAX_INLINE_ROWS` | `30` | Row threshold for inline vs. CSV delivery |\r\n\r\nSee [DOCUMENTATION.md](DOCUMENTATION.md#5-configuration-reference) for the full reference including Azure Blob and SQL settings.\r\n\r\n---\r\n\r\n## Security\r\n\r\n- **No LLM at the server** — code is executed directly; the server never makes model API calls.\r\n- **SQL safety** — two-level protection: keyword blocking + always-rollback transactions.\r\n- **Session isolation** — each session runs in its own interpreter process with an isolated filesystem.\r\n- **Config clamping** — client-supplied values can never exceed server-configured maximums.\r\n- **Blob SAS URLs** — time-limited, read-only access tokens for artifact downloads.\r\n\r\n---\r\n\r\n\r\n## License\r\n\r\n**Proprietary — Open Source**. See source file headers for the full license notice. Authorized use only.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadhanmohanreddy2301%2Fcodeboxmcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmadhanmohanreddy2301%2Fcodeboxmcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadhanmohanreddy2301%2Fcodeboxmcp/lists"}