Terminal MCP Server
Enables safe execution of terminal commands across different shells (bash, cmd, PowerShell) with configurable timeouts, working directories, and resource limits for command-line operations through AI assistants.
What is Terminal MCP Server?
Terminal MCP Server is a Model Context Protocol (MCP) server that allows AI assistants like Claude, Cursor, and VS Code to enables safe execution of terminal commands across different shells (bash, cmd, powershell) with configurable timeouts, working directories, and resource limits for command-line operations through ai ...
Enables safe execution of terminal commands across different shells (bash, cmd, PowerShell) with configurable timeouts, working directories, and resource limits for command-line operations through AI assistants.
This server falls under the Developer Tools category on MCPgee, the world's largest MCP server directory with 33,000+ servers.
Features
- Enables safe execution of terminal commands across different
Use Cases
Maintainer
Works with
Installation
Manual Installation
npx terminal-mcp-serverConfiguration
Configuration Details
claude_desktop_config.json
Performance
Response Metrics
Resource Usage
How to Set Up and Use Terminal MCP Server
Terminal MCP Server is a Python MCP server that enables AI assistants to safely execute terminal commands across multiple shell environments — bash, cmd, and PowerShell — with configurable timeouts, working directory scoping, and resource limits. Built with FastMCP and deployable via local Python, Docker (stdio or SSE), or Google Cloud Platform, it exposes a `run_command` tool that runs shell commands in a sandboxed workspace directory and returns the output to the AI. It is designed for developers who want to give AI assistants controlled access to their system's command line without unrestricted filesystem access.
Prerequisites
- Python 3.10 or higher and the `uv` package manager installed
- Git to clone the repository
- Docker (optional, for containerized or SSE deployment modes)
- An MCP-compatible client such as Claude Desktop
- A designated workspace directory for command execution (default: `~/mcp/workspace`)
Clone the repository
Download the terminal server source code from GitHub.
git clone https://github.com/theailanguage/terminal_server.git
cd terminal_serverInstall dependencies
Install the Python dependencies using uv. The pyproject.toml specifies all required packages including fastmcp.
uv syncCreate the workspace directory
The server executes commands inside `~/mcp/workspace` by default. Create this directory. All commands run by the AI will be scoped to this location.
mkdir -p ~/mcp/workspaceConfigure Claude Desktop
Add the terminal server to your claude_desktop_config.json. Use the absolute path to the cloned repository. The server runs via uv to ensure the correct virtual environment is used.
{
"mcpServers": {
"terminal": {
"command": "uv",
"args": [
"--directory", "/absolute/path/to/terminal_server",
"run",
"terminal_server.py"
]
}
}
}Optional: Deploy with Docker
For an isolated deployment, build the Docker image and update your config to use the containerized server. The workspace directory is mounted as a volume.
docker build -t terminal_server_docker .
# Then use this config:
# {
# "mcpServers": {
# "terminal_server": {
# "command": "docker",
# "args": ["run", "-i", "--rm", "--init",
# "-e", "DOCKER_CONTAINER=true",
# "-v", "/Users/yourname/mcp/workspace:/root/mcp/workspace",
# "terminal_server_docker"]
# }
# }
# }Restart Claude Desktop and verify
Restart Claude Desktop after saving the configuration. Ask Claude to run a simple command to confirm the terminal server is connected.
Terminal MCP Server Examples
Client configuration
Claude Desktop configuration for running terminal_server.py with uv, scoped to a workspace directory.
{
"mcpServers": {
"terminal": {
"command": "uv",
"args": [
"--directory", "/Users/yourname/terminal_server",
"run",
"terminal_server.py"
]
}
}
}Prompts to try
Ask Claude to execute shell commands through the terminal server's run_command tool.
- "Run the command ls in my workspace"
- "Execute echo Hello from Claude"
- "Check what Python version is installed with python3 --version"
- "Create a file called notes.txt in the workspace with the content 'test'"
- "List all files in the workspace directory including hidden files"Troubleshooting Terminal MCP Server
Server fails to start and Claude Desktop shows a connection error
Verify the `--directory` path in the config is an absolute path pointing to where you cloned the repo. Run `which uv` in a terminal to confirm uv is installed. If uv is not found, install it with `curl -LsSf https://astral.sh/uv/install.sh | sh`.
Commands run but return empty output or 'No such file or directory'
The server scopes all commands to `~/mcp/workspace`. Ensure this directory exists (`mkdir -p ~/mcp/workspace`). If you need a different working directory, edit the `DEFAULT_WORKSPACE` variable at the top of `terminal_server.py`.
Docker container exits immediately without running commands
Ensure the `-i` flag is present in the docker run args (it keeps stdin open for stdio transport). Also verify the volume mount path exists on your host and that the image was built successfully with `docker build -t terminal_server_docker .`.
Frequently Asked Questions about Terminal MCP Server
What is Terminal MCP Server?
Terminal MCP Server is a Model Context Protocol (MCP) server that enables safe execution of terminal commands across different shells (bash, cmd, powershell) with configurable timeouts, working directories, and resource limits for command-line operations through ai assistants. It connects AI assistants to external tools and data sources through a standardized interface.
How do I install Terminal MCP Server?
Follow the installation instructions on the Terminal MCP Server GitHub repository. Clone the repo, install dependencies, and add the server config to your AI client.
Which AI clients work with Terminal MCP Server?
Terminal MCP Server works with all major MCP-compatible AI clients including Claude Desktop, Claude Code, Cursor, VS Code (GitHub Copilot), Windsurf, and Cline.
Is Terminal MCP Server free to use?
Yes, Terminal MCP Server is open source and available under the NOASSERTION license. You can use it freely in both personal and commercial projects.
Terminal MCP Server Alternatives — Similar Developer Tools Servers
Looking for alternatives to Terminal MCP Server? Here are other popular developer tools servers you can use with Claude, Cursor, and VS Code.
Ecc
★ 188.2kThe agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Javaguide
★ 155.8kJava 面试 & 后端通用面试指南，覆盖计算机基础、数据库、分布式、高并发、系统设计与 AI 应用开发
Gemini CLI
★ 104.5kA secure MCP server that wraps the Google Gemini CLI, allowing clients to query Gemini models using local OAuth sessions without requiring an API key. It provides tools for model interaction and diagnostics with built-in protection against command in
Awesome MCP Servers
★ 87.3k⭐ Curated list of Model Context Protocol (MCP) servers - tools that extend Claude Desktop, Cursor, Windsurf, and other MCP clients with custom capabilities.
MCP Servers
★ 86.0kModel Context Protocol Servers
CC Switch
★ 77.5kA cross-platform desktop All-in-One assistant for Claude Code, Codex, OpenCode, OpenClaw, Gemini CLI & Hermes Agent. Only official website: ccswitch.io
Browse More Developer Tools MCP Servers
Explore all developer tools servers available in the MCPgee directory. Each server includes setup guides for Claude, Cursor, and VS Code.
Set Up Terminal MCP Server in Your Editor
Choose your AI client for step-by-step setup instructions.
Quick Config Preview
Add this to your claude_desktop_config.json or .cursor/mcp.json
Ready to use Terminal MCP Server?
Browse our complete directory of 33,000+ MCP servers, read setup guides for your editor, and start building with the Model Context Protocol.