Terminal MCP Server

A Model Context Protocol (MCP) server that enables execution of terminal commands through Claude Desktop.

Features

• Execute any terminal command with arguments and options
• Navigate between directories while maintaining state
• Get terminal environment information
• Full output capture (stdout, stderr, exit codes)
• Proper error handling and formatting

Prerequisites

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

Installation

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

Local Development 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 to your cloned repository.

2. Restart Claude Desktop

Available Tools

execute_command

• Execute any terminal command
• Supports command arguments and options
• Captures full output and exit codes

change_directory

• Change the current working directory
• Maintains state between commands
• Supports relative and absolute paths

get_current_directory

• Get the current working directory path

get_terminal_info

• Get information about the terminal environment
• Shows shell, user, platform, and recent command history

Usage Examples

Ask Claude to execute terminal commands like:

Can you check what's in my current directory?
-> Executes: ls -la

Can you tell me the current directory?
-> Executes: pwd

Can you change to the Downloads folder?
-> Executes: cd ~/Downloads

Security Considerations

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

Development

1. Watch for changes:

npm run watch

2. Test changes:

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

Project Structure

/
├── src/
│   └── index.ts    # Main server implementation
├── package.json    # Project configuration and dependencies
├── tsconfig.json  # TypeScript configuration
└── README.md      # This file

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License