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:

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.