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

Requirements

• Node.js 20+ (22+ recommended)

• npm

• Windows environment for full cmd/PowerShell support

Installation

1. Clone the repository:

git clone <repository-url>
cd Terminal-MCP

2. Install dependencies:

npm install

3. Build the server:

npm run build

4. Start the server:

npm start

For development mode during active changes:

npm run dev

Configuration

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

Example configuration:

{
  "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:

{
  "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:

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

{
  "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.