What is Terminal

The terminal MCP server is a Model Context Protocol server designed for executing terminal commands through Claude Desktop.

Use cases

Use cases include checking the contents of directories, retrieving current directory paths, changing directories, and obtaining terminal environment information.

How to use

To use the terminal MCP server, clone the repository, install the dependencies, build the project, and configure Claude Desktop to recognize the server. After setup, you can ask Claude to execute terminal commands.

Key features

Key features include the ability to execute any terminal command with arguments, navigate directories while maintaining state, capture full output including stdout and stderr, and handle errors properly.

Where to use

undefined

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