home / mcp / host terminal mcp server

Host Terminal MCP Server

Run terminal commands on your computer through Claude using local stdio and HTTP transports to enable shared command execution.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "ankitaa186-host-terminal-mcp": {
      "url": "http://localhost:8099"
    }
  }
}

You can run terminal commands on your computer from Claude using Host Terminal MCP. It supports a local stdio transport for Claude Desktop and MCP Inspector, and an HTTP transport for external services over the network, enabling integrations like chatbots running in containers or other machines to execute host commands.

How to use

You use the MCP by connecting Claude to either a local stdio server or an HTTP server. The stdio transport lets Claude send commands directly on your machine, while the HTTP transport exposes a REST API that external services can call to run commands. You can perform day-to-day tasks like listing files, checking system status, or querying running services, all while keeping permissions under control.

How to install

Prerequisites: you need a working environment with uv installed to manage MCP components, and you should have Claude Desktop available if you want the stdio integration.

# Install the MCP package for local use
uv tool install host-terminal-mcp

# Add to Claude Desktop config and restart

Configuration and usage notes

Two transports are available: stdio and http. Use stdio for Claude Desktop or MCP Inspector. Use http to allow external services to call into the MCP server via a REST API.

HTTP endpoints provided include health checks and command execution. Your external service can POST to the execute endpoint to run a command, optionally specifying a working directory. Use the health endpoint to verify the server is up.

Endpoints and capabilities

The following endpoints are exposed when running in HTTP mode: health, execute, cd, cwd, and permissions. You can perform a health check, execute commands, change and query the current working directory, and retrieve permission configurations.

Permission modes

Control which commands Claude can run through the MCP server. There are three modes: allowlist (default), ask, and allow_all. The allowlist mode restricts execution to pre-approved commands, while ask prompts you when unknown commands are requested. The allow_all mode permits all commands except those explicitly blocked.

Important: a blocked command always takes precedence over allowed or session-approved commands.

Default allowed commands

Out of the box, a variety of safe commands are permitted for file listing, viewing, searching, basic Git read-only operations, system information, and read-only network interactions. Examples include ls, cat, grep, git status, uname, ping, curl, and docker ps for read-only contexts.

Security and safety notes

Only run commands you fully trust. Use the allowlist mode for safety, review the explicit white list of commands, and be mindful of potentially dangerous operations. The system prevents dangerous actions such as recursive deletions, privilege escalations, and destructive disk operations from being executed.

Development and maintenance

If you are contributing to the MCP or testing locally, you can follow standard build and run workflows to verify changes. Use the provided make targets for installation, running in stdio mode, starting the HTTP server, and stopping or inspecting status.

Config

Configuration is stored in the following location and can be initialized with a command. You can extend the allowed commands and adjust behavior such as timeouts and output size.

# Example default config generated by the tool
permission_mode: allowlist
timeout_seconds: 300
max_output_size: 100000
shell: /bin/bash
allowed_directories:
  - /Users/me
environment_passthrough:
  - PATH
  - HOME
  - USER
  - LANG
  - LC_ALL

HTTP server and endpoints (example usage)

To run the HTTP server, you start the MCP with HTTP enabled and a port number, then external services can call the execute endpoint to run commands.

# Start the HTTP server on port 8099 in the background
nohup host-terminal-mcp --http --port 8099 > /tmp/host-terminal-mcp.log 2>&1 &

# Optional: specify permission mode
nohup host-terminal-mcp --http --port 8099 --mode ask > /tmp/host-terminal-mcp.log 2>&1 &

# Verify health
curl http://localhost:8099/health

MCP server commands and endpoints summary

These commands and endpoints are used to interact with the MCP server from Claude or external services. Use the stdio flow for local execution and the HTTP flow for networked integrations.

Available tools

health

Health check endpoint to verify MCP server is running.

execute

Endpoint to run a command with optional working directory and capture stdout, stderr, and exit code.

cd

Change the working directory for subsequent commands.

cwd

Retrieve the current working directory for the MCP session.

permissions

Get the current permission configuration and mode.