Metadata-Version: 2.2
Name: local-terminal-mcp
Version: 0.1.1
Summary: Connect your local terminal to AI agents via MCP (Model Context Protocol). Provides secure shell, file read/write, and directory listing tools over WebSocket.
Author: Agent Builder Team
License: MIT
Keywords: mcp,ai,agent,terminal,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: System :: Shells
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=0.9.0
Requires-Dist: websockets>=12.0
Requires-Dist: pydantic>=2.0
Requires-Dist: pydantic-settings>=2.0
Requires-Dist: click>=8.1
Requires-Dist: python-dotenv>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.4; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
Requires-Dist: pytest-cov>=4.1; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: mypy>=1.5; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"

# 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
