Terminal MCP Server

Terminal MCP Server exposes one MCP tool, run_command, that runs shell commands on the host and returns stdout, stderr, exit code, duration, timeout status, and truncation status.

I personally use it with ChatGPT, so ChatGPT can access my local system in a Codex-like way.

This is intentionally powerful. If the service runs as root, the MCP client has root shell capability. Put it behind HTTPS, require OAuth/OIDC authentication, restrict who can receive the required scope, and review audit logs.

Features

• Streamable HTTP MCP transport.

• run_command tool implemented with bash -lc.

• JWT access-token validation through any OAuth/OIDC server that publishes JWKS.

• Optional direct Microsoft Entra ID validation.

• Optional bearer-token and in-memory OAuth modes for local testing.

• OAuth protected-resource metadata for ChatGPT and other MCP clients.

• JSON-lines audit log with command, result metadata, source IP, session ID, and non-secret token claims.

Related MCP server: mcp-shell

Demo

Recommended Architecture

Use a real OAuth/OIDC authorization server in front of this MCP server:

MCP client -> Terminal MCP Server
              |
              validates JWT access token
              |
              OAuth/OIDC authorization server

The authorization server should:

• authenticate users with your preferred identity providers;

• decide which users may receive the command-execution scope;

• issue JWT access tokens with a stable issuer, audience, and scope;

• expose a JWKS endpoint.

The MCP server only validates tokens. It does not need client secrets for the OAuth client used by ChatGPT or another MCP client.

Quick Start

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
set -a
. ./.env
set +a
python server.py

The MCP endpoint is:

http://127.0.0.1:8767/mcp

For production, put HTTPS in front of the service and set MCP_RESOURCE_BASE_URL to the public origin, for example:

MCP_RESOURCE_BASE_URL=https://mcp.example.com

The advertised MCP resource becomes:

https://mcp.example.com/mcp

Configuration

Common settings:

MCP_HOST=127.0.0.1
MCP_PORT=8767
MCP_TRANSPORT=streamable-http
MCP_COMMAND_TIMEOUT=30
MCP_COMMAND_MAX_TIMEOUT=120
MCP_MAX_OUTPUT_BYTES=131072
MCP_AUDIT_LOG=/var/log/terminal-mcp/audit.log

Recommended JWT mode:

MCP_AUTH_MODE=jwt
MCP_JWKS_URI=https://auth.example.com/jwks
MCP_JWT_ISSUER=https://auth.example.com
MCP_JWT_AUDIENCE=https://mcp.example.com/mcp
MCP_JWT_ALGORITHM=RS256
MCP_REQUIRED_SCOPES=terminal.run
MCP_ADVERTISED_SCOPES=terminal.run
MCP_OAUTH_ISSUER=https://auth.example.com
MCP_RESOURCE_BASE_URL=https://mcp.example.com

The token must contain the required scope. Depending on your provider this is usually represented as scp, scope, or a compatible claim understood by FastMCP's JWT verifier.

OAuth Discovery Endpoints

The server exposes:

/.well-known/oauth-protected-resource
/.well-known/oauth-protected-resource/mcp
/.well-known/oauth-authorization-server

MCP_OAUTH_ISSUER controls the authorization-server issuer advertised to MCP clients. For a generic OAuth/OIDC provider, that issuer is normally your auth server origin.

ChatGPT Connector Setup

Use these values when creating a ChatGPT connector:

Server URL: https://mcp.example.com/mcp
OAuth client ID: <client id from your authorization server>
OAuth client secret: <client secret from your authorization server>
Authorization URL: https://auth.example.com/authorize
Token URL: https://auth.example.com/token
Scope: terminal.run

If ChatGPT sends a resource parameter during OAuth, configure MCP_JWT_AUDIENCE to match the access token audience issued for that resource, often the full MCP resource URL:

MCP_JWT_AUDIENCE=https://mcp.example.com/mcp

Microsoft Entra ID Direct Mode

You can validate Entra ID tokens directly:

MCP_AUTH_MODE=entra
MCP_ENTRA_TENANT_ID=<tenant-id>
MCP_ENTRA_AUDIENCE=api://<api-application-client-id>
MCP_REQUIRED_SCOPES=terminal.run
MCP_ENTRA_ALLOWED_OIDS=<allowed-user-object-id>[,<another-object-id>]

Use two app registrations:

1. API app: exposes the terminal.run delegated scope.
2. Client app: has the MCP client's redirect URI and a client secret.

MCP_ENTRA_ALLOWED_OIDS is optional but strongly recommended. When set, only those Entra user object IDs can call run_command.

Local Testing Modes

Bearer-token mode:

MCP_AUTH_MODE=bearer
MCP_BEARER_TOKEN=<random token>

Development OAuth mode:

MCP_AUTH_MODE=memory_oauth
MCP_PUBLIC_BASE_URL=https://mcp.example.com
MCP_RESOURCE_BASE_URL=https://mcp.example.com
MCP_OAUTH_CLIENT_ID=terminal-mcp
MCP_OAUTH_CLIENT_SECRET=<random secret>
MCP_OAUTH_REDIRECT_URIS=https://chatgpt.com/connector/oauth/<connector-id>

Do not use memory_oauth in production. Tokens and client registrations are in-memory and restart-sensitive.

systemd

An example unit is available at:

examples/terminal-mcp.service

Typical layout:

/opt/terminal-mcp/server.py
/opt/terminal-mcp/.venv
/etc/terminal-mcp/env

Install and start:

sudo cp examples/terminal-mcp.service /etc/systemd/system/terminal-mcp.service
sudo systemctl daemon-reload
sudo systemctl enable --now terminal-mcp.service

Audit Log

Command calls are appended as JSON lines to MCP_AUDIT_LOG. The audit record contains command metadata and non-secret authentication context. It does not log access tokens.

Security Notes

• Prefer running with the minimum Linux privileges needed for your use case.

• Restrict terminal.run issuance in your authorization server.

• Put HTTPS and a WAF or reverse proxy in front of the service.

• Keep client secrets in the OAuth client or authorization server, not in this MCP resource server.

• Rotate keys and review audit logs regularly.