Terminal

🚀 Terminal MCP Server

A Model Context Protocol (MCP) server that executes terminal commands via Claude Desktop.

🚀 Quick Start

The Terminal MCP Server enables the execution of terminal commands through Claude Desktop, offering a seamless way to interact with your system's terminal environment.

✨ Features

• Execute any terminal command with arguments and options.
• Switch between directories while maintaining state.
• Retrieve terminal environment information.
• Capture the full output (stdout, stderr, exit code).
• Implement proper error handling and formatting.

📦 Installation

Prerequisites

• Node.js v18 or higher
• TypeScript
• Claude Desktop

Steps

1. Clone the repository:

git clone https://github.com/stat-guy/terminal.git
cd terminal

2. Install dependencies:

npm install

3. Build the project:

npm run build

📚 Documentation

Local Development Environment Setup

1. Create or edit your Claude Desktop configuration file:
   • On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • On Windows: %APPDATA%\\Claude\\claude_desktop_config.json

Add the following configuration:

{
  "mcpServers": {
    "terminal": {
      "command": "node",
      "args": [
        "[PATH_TO_REPO]/dist/index.js"
      ],
      "env": {
        "PERMISSION_REQUIRED": "true"
      }
    }
  }
}

Replace [PATH_TO_REPO] with the actual path of the cloned repository.

2. Restart Claude Desktop.

Available Tools

execute_command

• Execute any terminal command.
• Support commands with arguments and options.
• Capture the full output and exit code.

change_directory

• Change the current working directory.
• Maintain state between commands.
• Support relative and absolute paths.

get_current_directory

• Get the path of the current working directory.

get_terminal_info

• Retrieve terminal environment information.
• Display the shell, user, platform, and recent command history.

💻 Usage Examples

Let Claude execute terminal commands, for example:

Can you check what files are in my current directory?
-> Execute: ls -la

Can you tell me what my current directory is?
-> Execute: pwd

Can you switch to the Downloads folder?
-> Execute: cd ~/Downloads

🔧 Technical Details

Security Considerations

• The server requires explicit user permission via Claude Desktop for command execution.
• Environment variables can be controlled through configuration.
• Command execution includes timeout and error handling.

Development

1. Watch for changes:

npm run watch

2. Test changes:

• Modify source files in src/.
• Rebuild using npm run build.
• Restart Claude Desktop to load the changes.