# 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:
```bash
uv venv
```

2. Activate the virtual environment:
```bash
source .venv/bin/activate
```

3. Install dependencies:
```bash
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:
```json
{
    "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](https://modelcontextprotocol.io/docs/tools/inspector) tool, which provides a web interface for interacting with MCP servers.

1. Install MCP Inspector:
```bash
npm install -g @modelcontextprotocol/inspector
```



2. In another terminal, run the inspector:
```bash
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:
```python
# 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`:
```python
# 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:
```python
# 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:
```bash
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