terminal-mcp-server

Terminal MCP Server

A simple MCP server that executes terminal commands and provides a terminal command cheat sheet. Also demonstrates potential security vulnerabilities in MCP server implementations.

Features

1. Terminal Command Execution

   • Execute any terminal command
   • Get stdout, stderr, and return code
   • Error handling

2. Security Vulnerability Demo

   • magical_tool demonstrates unsafe command execution
   • Shows how malicious code can be executed
   • Highlights importance of secure implementation

3. Terminal Command Cheat Sheet

   • 30 essential terminal commands
   • Common options and flags
   • Usage examples

Installation

1. Create a virtual environment:

uv venv

2. Activate the virtual environment:

source .venv/bin/activate

3. Install dependencies:

uv pip install -e .

Adding to Claude

1. Locate Claude's desktop configuration file:

~/Library/Application Support/Claude/claude_desktop_config.json

2. Add the terminal server configuration:

{
    "mcpServers": {
        "terminal": {
            "command": "/path/to/terminal-mcp-server/.venv/bin/python",
            "args": [
                "/path/to/terminal-mcp-server/src/server.py"
            ]
        }
    }
}

Replace /path/to/terminal-mcp-server with the actual path where you cloned this repository.

3. Restart Claude to load the new configuration.

Testing with MCP Inspector

You can test the MCP server using the MCP Inspector tool, which provides a web interface for interacting with MCP servers.

1. Install MCP Inspector:

npm install -g @modelcontextprotocol/inspector

2. In another terminal, run the inspector:

npx @modelcontextprotocol/inspector

This will start a web application locally where you can:

• Connect to your MCP server
• Test all available tools
• View tool responses
• Inspect resources
• Debug communication

Usage

The server provides:

1. run_command tool:

# Safe command execution
result = await run_command("ls -la")
print(result["stdout"])  # Command output
print(result["stderr"])  # Any errors
print(result["return_code"])  # Exit code

2. magical_tool:

# WARNING: Demonstrates unsafe command execution
# Shows how external commands can be executed without proper validation
result = await magical_tool()
print(result["stdout"])  # Executed command output
print(result["stderr"])  # Any errors
print(result["return_code"])  # Command exit code

3. terminal_commands_cheat_sheet resource:

# Access terminal commands cheat sheet
commands = await terminal_commands_cheat_sheet()
print(commands)  # List of commands with examples

Security Implications

The magical_tool demonstrates a common security vulnerability where user inputs or file paths are used directly in command execution without proper validation. This could allow:

1. Command Injection
2. Arbitrary File Access
3. System Manipulation

This is intentionally included as an educational example of what NOT to do in production systems.

Development

1. Clone the repository
2. Create and activate virtual environment as shown above
3. Install dependencies
4. Run the server:

uv run src/server.py

Error Handling

• All tools handle errors gracefully
• Failed commands return error messages in stderr
• Resource access failures return error messages
• Non-zero return codes indicate command failures

License

MIT