# Terminal MCP Server

A production-ready Model Context Protocol (MCP) server for interacting with local terminal sessions from AI-powered clients such as Claude Desktop, Cursor, VS Code, LM Studio, and Continue.dev. This project enables secure, session-based command execution, file manipulation, and system inspection directly through MCP tools.

## Overview

Terminal MCP Server bridges the gap between AI assistants and your local shell environment. It exposes a curated set of tools for:

- Creating and managing persistent terminal sessions
- Executing commands in cmd, PowerShell, or PowerShell Core
- Browsing and modifying files and folders
- Inspecting system information and running processes
- Enforcing configurable security boundaries for safe usage

## Key Features

- Persistent terminal sessions with session IDs and working directories
- Support for cmd and PowerShell execution environments
- Streaming command output for interactive workflows
- File operations including read, write, copy, move, and delete
- Directory management with recursive create/delete support
- Environment variable and process inspection tools
- Configurable security controls, including allowed roots and dangerous command restrictions

## Supported Tools

| Tool | Purpose |
|------|---------|
| create_session | Create a new terminal session |
| execute_command | Run a command in a terminal session |
| execute_powershell | Run PowerShell-specific commands |
| list_sessions | View active sessions |
| close_session | End an existing session |
| current_directory | Retrieve the working directory |
| change_directory | Move to a new working directory |
| list_directory | List folder contents |
| read_file / write_file | Read or write file contents |
| copy_file / move_file / delete_file | Manage files |
| create_directory / delete_directory | Manage folders |
| system_info | Get OS and hardware information |
| environment_variables | Inspect session environment variables |
| process_list | List running processes |

## Requirements

- Node.js 20+ (22+ recommended)
- npm
- Windows environment for full cmd/PowerShell support

## Installation

1. Clone the repository:

```bash
git clone <repository-url>
cd Terminal-MCP
```

2. Install dependencies:

```bash
npm install
```

3. Build the server:

```bash
npm run build
```

4. Start the server:

```bash
npm start
```

For development mode during active changes:

```bash
npm run dev
```

## Configuration

The server uses a configuration file named config.json. You can customize security and terminal behavior there.

Example configuration:

```json
{
  "allowedRoots": ["C:\\Users", "C:\\Projects", "C:\\Temp"],
  "allowCMD": true,
  "allowPowerShell": true,
  "allowDangerousCommands": false,
  "maxOutputSize": 10485760,
  "sessionTimeout": 1800000,
  "maxSessions": 50,
  "security": {
    "strictMode": false,
    "enableAuditLog": true
  }
}
```

## MCP Client Configuration

To use this server with an MCP-compatible client, register it in the client configuration with the command and working directory for this project.

Example configuration:

```json
{
  "mcpServers": {
    "windows-terminal": {
      "command": "node",
      "args": ["C:/path/to/Terminal-MCP/dist/server.js"],
      "cwd": "C:/path/to/Terminal-MCP"
    }
  }
}
```

If you are using the repository’s provided MCP setup files, refer to mcp.json and MCP_SETUP.md for client-specific examples.

## Quick Usage Example

1. Create a session
2. Execute a command
3. Inspect output and manage files

Example workflow:

```json
{
  "tool": "create_session",
  "args": {
    "shell": "powershell",
    "cwd": "C:/Users"
  }
}
```

```json
{
  "tool": "execute_command",
  "args": {
    "sessionId": "session_123",
    "command": "Get-Process | Select-Object -First 5"
  }
}
```

## Security Notes

Security is intentionally configurable and conservative by default:

- Dangerous commands are disabled unless explicitly allowed
- Only configured roots are permitted for file and directory operations
- Session limits and timeouts help prevent resource abuse
- Audit logging is enabled by default

It is recommended to review the settings in config.json before using the server in a shared or production environment.

## Project Structure

- src/server.js - MCP server entry point
- src/tools - Tool implementations for sessions, commands, and file operations
- src/terminal - Terminal session management
- src/security - Validation and security helpers
- config.json - Runtime configuration

## License

This project is licensed under the MIT License.