Python Runner MCP Server (Turhal AI)

Python kodunu izole subprocess'lerde calistiran, stdio transport uzerinden konusan, production-ready bir MCP (Model Context Protocol) sunucusu. Python MCP SDK'nin FastMCP sinifi ile yazilmistir; Claude Desktop ve OpenClaw Gateway ile dogrudan uyumludur.

Icerik

Related MCP server: MCP Executor Server

Ozellikler

• Izolasyon: Her run_python cagrisi ayri bir OS process'inde calisir.

• Kaynak limitleri (Linux/macOS, resource.setrlimit ile):

  • CPU suresi (RUNNER_MAX_CPU_SECONDS)

  • Bellek / adres alani (RUNNER_MAX_MEMORY_MB)

  • Process sayisi (RUNNER_MAX_PROCESSES)

  • Yazilabilir dosya boyutu (RUNNER_MAX_FILE_SIZE_MB)

  • Core dump kapali

• Zaman asimi: asyncio.wait_for ile duvar-saati (wall clock) timeout; asilirsa process kill() edilir.

• Cikti limiti: stdout/stderr RUNNER_MAX_OUTPUT_CHARS karakterde kirpilir.

• Eszamanlilik kontrolu: asyncio.Semaphore ile ayni anda calisan process sayisi RUNNER_MAX_CONCURRENT ile sinirlanir; sunucu tek process icinde birden fazla istegi guvenle kuyruklar.

• Loglama: Tum loglar stderr'e yazilir (stdout, MCP JSON-RPC protokolu icin ayrilmistir). Her istek request_id ile izlenebilir.

• Hata yonetimi: Beklenen ve beklenmeyen tum hatalar yakalanip kullaniciya duzgun bicimlendirilmis metin olarak donulur; sunucu process'i asla cokmez.

• Docker-native: Non-root kullanici, read-only dosya sistemi, network: none, cap_drop: ALL ile calisacak sekilde tasarlanmistir.

Guvenlik kapsami ve sinirlari (onemli)

resource.setrlimit ve subprocess izolasyonu, process-seviyesinde bir koruma sağlar (kaçak bellek/CPU tüketimini, fork bombasını, zaman aşımını önler). Bu, çalıştırılan kodun container dışına çıkmasını veya ağa erişmesini engellemez.

Production'da tam izolasyon icin:

1. Bu sunucuyu mutlaka Docker container icinde, docker-compose.yml / openclaw.gateway.example.json ornegindeki gibi --network=none, --read-only, --cap-drop=ALL bayraklariyla calistirin.

2. Daha yuksek guven seviyesi gerekiyorsa (coklu kiracili / multi-tenant sistemler), gVisor, nsjail veya Firecracker gibi bir OS-seviyesi sandbox katmani ekleyin - bu dosyalar bunu kolaylastiracak sekilde (ag kapali, salt-okunur FS, dusuk kaynak limitleri) hazirlanmistir ama bunlarin yerini tutmaz.

3. Kod, -I -S bayraklariyla (izole mod, site-packages'siz) calistirilir; yine de guvenilmeyen kullanicilardan gelen kodu calistiriyorsaniz agi mutlaka kapali tutun.

Kurulum (yerel, container'siz)

python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt
python server.py

Sunucu stdio uzerinden calisir; dogrudan terminalden calistirdiginizda JSON-RPC mesaji bekleyerek beklemede kalir (bu normaldir - bir MCP istemcisi baglanmadan cikti gormezsiniz).

Docker ile calistirma

docker build -t turhal-ai/python-runner-mcp:latest .

docker run -i --rm \
  --network=none \
  --read-only \
  --tmpfs /tmp:size=64m,mode=1777 \
  --security-opt no-new-privileges:true \
  --cap-drop=ALL \
  --memory=512m --cpus=1.0 --pids-limit=64 \
  turhal-ai/python-runner-mcp:latest

Veya build/manuel test icin:

docker compose build
docker compose run --rm python-runner

docker compose up kullanmayin - MCP stdio, istemcinin container'i docker run -i ile spawn edip stdin/stdout'a dogrudan baglanmasini gerektirir; arka planda calisan bir compose servisi bu modelle uyumlu degildir. docker-compose.yml yalnizca build/test amaclidir.

Claude Desktop entegrasyonu

claude_desktop_config.json icine openclaw.gateway.example.json dosyasindaki python-runner (yerel) veya python-runner-docker (onerilen, sandboxlanmis) blogunu ekleyin ve yollari kendi ortaminiza gore guncelleyin.

OpenClaw Gateway entegrasyonu

openclaw.gateway.example.json dosyasi, Gateway'in mcpServers bolumune dogrudan tasinabilecek bicimde hazirlanmistir. Docker varyanti, agi kapali ve read-only bir container icinde calisacagi icin production'da onerilir.

Konfigurasyon (ortam degiskenleri)

run_python araci - kullanim

Girdi:

{
  "code": "print(sum(range(10)))",
  "timeout": 5
}

Cikti (metin):

[request_id=a1b2c3d4]
--- stdout ---
45

--- exit_code: 0 | duration: 0.041s ---

Zaman asimi, hata ve kirpilma durumlari da ayni bicimde, request_id ile izlenebilir sekilde donulur; loglarda ayni request_id ile eslestirilebilir.

Test

python -c "
import asyncio
from server import _run_code_in_subprocess

async def main():
    r = await _run_code_in_subprocess('print(1+1)', timeout=5, request_id='test')
    print(r.to_text())

asyncio.run(main())
"