Skip to content

README.md

Latest commit

 

History

History
104 lines (68 loc) · 2.51 KB

README.md

File metadata and controls

104 lines (68 loc) · 2.51 KB

gptsh MCP Server

Minimal MCP server that exposes a persistent bash session via a sandboxed executor. Includes OAuth 2.1 (auth code + PKCE) and SQLite-backed persistence for codes/tokens.

Quick start

  1. Copy the example config and edit values:
cp config.env.example config.env
  1. Build:
make build
  1. Run:
./run.sh

The MCP endpoint is available at:

  • http(s)://<host>/mcp

The legacy exec endpoint remains at:

  • http(s)://<host>/exec

Configuration

All configuration lives in config.env (loaded by run.sh).

Core settings:

  • LISTEN_ADDR – address/port to bind (e.g. 0.0.0.0:8002)
  • MAX_OUTPUT_CHARS
  • EXECUTOR_PATH

Sandbox settings (executor):

  • WRITE_ALLOW – colon-separated allowed write paths
  • BIND_TCP_ALLOW – colon-separated allowed bind ports
  • ALLOW_OUTGOING_TCP – true/false
  • BASH_PATH

MCP auth modes

Set AUTH_MODE to one of:

  • api_key – default, uses API_KEY as Bearer token
  • oauth – OAuth 2.1 authorization code + PKCE
  • any – accept either API key or OAuth
  • none – no auth

OAuth (self-contained)

This project includes a minimal OAuth provider with a login form. It requires SQLite for persistence.

Required (when OAuth is enabled):

  • OAUTH_CLIENT_ID
  • OAUTH_REDIRECT_URIS – space-separated list of allowed redirect URIs
  • OAUTH_SQLITE_PATH – path to SQLite file (e.g. ./oauth.sqlite)
  • OAUTH_USERNAME / OAUTH_PASSWORD – credentials for the login form

Optional:

  • OAUTH_ALLOWED_SCOPES – space-separated scopes
  • OAUTH_TOKEN_TTL_SECONDS
  • OAUTH_CODE_TTL_SECONDS
  • PUBLIC_URL – external URL if behind a proxy
  • AUTH_SERVER_URL – override OAuth issuer URL (defaults to PUBLIC_URL)

OAuth endpoints:

  • /.well-known/oauth-protected-resource
  • /.well-known/oauth-authorization-server
  • /oauth/authorize
  • /oauth/token

ChatGPT MCP setup notes

  • ChatGPT requires OAuth 2.1 auth code + PKCE (client credentials are not supported).
  • Configure static client credentials in ChatGPT and set OAUTH_CLIENT_ID to match. This server accepts public clients only (no client secret).
  • Ensure PUBLIC_URL is set if running behind a proxy, and that OAUTH_REDIRECT_URIS includes ChatGPT’s redirect URI.

Tests

make test

The test suite builds server/executor and runs sandbox behavior checks.

Files

  • cmd/server – HTTP/MCP server
  • cmd/executor – sandboxed executor
  • internal/mcp – MCP JSON-RPC handler
  • internal/auth – OAuth + auth middleware