Hızlı başlangıç¶

Bu kılavuz ilk runtime olarak Docker Compose, ilk client olarak ChatGPT kullanır. Bunlar bağımsız seçimlerdir: Docker, VS Code extension, binary, Python ve stdio runtime seçenekleridir; ChatGPT ve genel MCP client’ları client seçenekleridir. Tam harita için runtime seçenekleri ve deployment modeli bölümüne bakın.

Gereksinimler¶

Compose v2 ile Docker Engine.
ChatGPT Web üzerinden bağlanacaksa herkese açık HTTPS endpoint.
Özel bir workspace directory.
Uzun ve rastgele OAuth admin PIN ile JWT secret.

Warning

Bağlı model yapılandırılmış workspace üzerinde işlem yapabilir. Servisi disposable container veya VM içinde çalıştırın ve host-control resources bağlamayın.

1. Clone ve yapılandırma¶

git clone https://github.com/fwerkor/local-shell-mcp.git
cd local-shell-mcp
cp .env.example .env

.env dosyasını düzenleyin:

LOCAL_SHELL_MCP_PUBLIC_BASE_URL=https://your-public-host.example.com
LOCAL_SHELL_MCP_AUTH_MODE=oauth
LOCAL_SHELL_MCP_OAUTH_ADMIN_PIN=change-me-long-random-pin
LOCAL_SHELL_MCP_OAUTH_JWT_SECRET=change-me-64-hex-random-secret
CLOUDFLARE_TUNNEL_TOKEN=

2. Sunucuyu başlatma¶

mkdir -p workspaces/default
docker compose up -d

Durumu kontrol edin:

docker compose ps
docker compose logs --tail=100 local-shell-mcp
curl -i http://127.0.0.1:8765/healthz

Sağlıklı yanıt HTTP 200 döndürür.

3. HTTPS yayınlama¶

Cloudflare Tunnel sidecar için:

docker compose --profile tunnel up -d

Cloudflare Zero Trust içinde public hostname’i şuraya yönlendirin:

http://local-shell-mcp:8765

Caddy, Nginx, Traefik, Nginx Proxy Manager veya başka bir reverse proxy için HTTPS traffic’i 127.0.0.1:8765 ya da container network address’e iletin.

4. ChatGPT bağlama¶

MCP endpoint’i kullanın:

https://your-public-host.example.com/mcp

OAuth ve tool approval işlemini tamamlamak için ChatGPT connector kılavuzunu izleyin.

5. Tool erişimini güvenle doğrulama¶

Modele şunu isteyin:

local-shell-mcp kullan. Önce environment_get çağır, sonra workspace root’u listele. Henüz dosya değiştirme.

Beklenen read-only tools:

environment_get
file_list
file_tree
file_read

6. Sınırlandırılmış bir coding task ile başlama¶

İyi bir ilk task:

Bu repository’yi incele, project layout’u özetle, açıksa mevcut test suite’i çalıştır ve dosyaları değiştirme.

Bağlantı doğrulandıktan sonra daha belirgin talimat verin:

Başarısız testi düzelt. Önce ilgili dosyaları oku, en küçük patch’i yap, hedef testi çalıştır, sonra git diff göster. Ben onaylamadan commit yapma.

Güncelleme¶

docker compose pull
docker compose up -d
curl -i http://127.0.0.1:8765/healthz

Tunnel profile kullanıyorsanız:

docker compose --profile tunnel pull
docker compose --profile tunnel up -d
curl -i http://127.0.0.1:8765/healthz

Sonraki sayfalar¶

İhtiyaç	Sayfa
runtime ve client seçimlerini anlama	Runtime seçenekleri ve deployment modeli
Docker Compose ile çalıştırma	Docker Compose runtime
VS Code’dan çalıştırma	VS Code extension runtime
release binary ile çalıştırma	Standalone binary runtime
Python veya source checkout ile çalıştırma	Python runtimes
ChatGPT’yi client olarak ekleme	ChatGPT connector
tools seçme ve daha iyi prompt yazma	Kullanım kalıpları
HPC, NPU/GPU veya NAT makinesi bağlama	Uzak workers
Tüm MCP tools’u anlama	Tools referansı