local-terminal-mcp 0.1.0

Connect your local terminal to AI agents via MCP (Model Context Protocol). Provides secure shell, file read/write, and directory listing tools over WebSocket.

Local Terminal MCP Server

Connect your local terminal to AI agents via MCP (Model Context Protocol). Provides secure shell execution, file read/write, and directory listing — all over an authenticated WebSocket connection.

Installation

pip install local-terminal-mcp

Requires Python 3.10+.

Quick Start

# Connect to Agent Builder (opens browser for authentication)
local-terminal-mcp connect --team <your_team_id>

On first run, a browser window opens for OAuth authentication. Subsequent runs use a cached token — no repeated logins.

Keep the terminal window open while the connection is active. Press Ctrl+C to disconnect.

Available Tools

Once connected, AI agents can use these tools on your machine:

Tool	Description
execute_command	Run shell commands
read_file	Read file contents
write_file	Write to files
list_directory	List directory contents

Security

All commands are validated before execution. By default, dangerous commands (rm -rf /, shutdown, mkfs, etc.) are blocked, and sensitive system paths (/etc, /sys, /proc, /root) are protected.

For maximum security, enable whitelist mode — only explicitly allowed commands will run:

LT_MCP_WHITELIST_ONLY=true local-terminal-mcp connect --team <team_id>

Security summary

• Commands validated before execution (dangerous commands blocked)
• Sensitive system paths are protected
• All connections require JWT authentication (OAuth PKCE)
• Configurable whitelist mode

Configuration

Configuration is done via environment variables (prefix LT_MCP_):

Variable	Default	Description
LT_MCP_WHITELIST_ONLY	false	Only allow whitelisted commands
LT_MCP_BLOCKED_PATHS	["/etc","/sys","/proc","/root","/boot"]	Protected paths
LT_MCP_MAX_COMMAND_TIMEOUT	300	Max command timeout (seconds)
LT_MCP_LOG_LEVEL	INFO	Logging level

You can also place these in a .env file in the working directory.

CLI Commands

local-terminal-mcp connect    # Connect to Agent Builder
local-terminal-mcp status     # Show auth & config status
local-terminal-mcp logout     # Clear cached tokens
local-terminal-mcp test       # Test tools locally (no server needed)
local-terminal-mcp version    # Show version

Advanced Usage

CI / Headless Environments

Pass a JWT token directly (skips browser auth):

local-terminal-mcp connect --token "YOUR_JWT_TOKEN" --team <team_id>

Custom Server URL

local-terminal-mcp connect --url wss://your-server.example.com --team <team_id>

License

MIT