local-terminal-mcp 0.1.1
Connect your local terminal to AI agents via MCP (Model Context Protocol). Provides secure shell, file read/write, and directory listing tools over WebSocket.
License: MIT
Requires Python: >=3.10
Keywords: mcp, ai, agent, terminal, model-context-protocol

# Local Terminal MCP Server

[![PyPI version](https://img.shields.io/pypi/v/local-terminal-mcp.svg)](https://pypi.org/project/local-terminal-mcp/)
[![Python 3.10+](https://img.shields.io/pypi/pyversions/local-terminal-mcp.svg)](https://pypi.org/project/local-terminal-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)

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

```bash
pip install local-terminal-mcp
```

Requires **Python 3.10+**.

## Quick Start

```bash
# 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:

```bash
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

```bash
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):

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

### Custom Server URL

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

## License

MIT