iTerm Terminal MCP server

This MCP server provides seamless integration with your iTerm terminal sessions, allowing AI models to interact with your terminal while efficiently managing token usage. The server gives models the ability to view selected terminal output and execute commands in your existing iTerm sessions.

Installation

Setup for Claude Desktop

To integrate with Claude Desktop, you'll need to add the server configuration to your Claude Desktop config file:

On macOS:

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

On Windows:

%APPDATA%/Claude/claude_desktop_config.json

Add the following configuration to the file:

{
  "mcpServers": {
    "iterm-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "iterm-mcp"
      ]
    }
  }
}

Automated Installation via Smithery

For a simpler installation process, you can use Smithery to automatically set up iterm-mcp:

npx -y @smithery/cli install iterm-mcp --client claude

Requirements

Before using iterm-mcp, ensure you have:

• iTerm2 installed and running
• Node.js version 18 or greater

Usage

Available Tools

The iterm-mcp server provides three main tools that models can use to interact with your terminal:

• write_to_terminal - Sends text or commands to your active iTerm terminal window. It returns the number of lines of output produced by the command.

• read_terminal_output - Retrieves a specified number of lines from the active iTerm terminal, allowing the model to see terminal output.

• send_control_character - Sends control characters (like Ctrl+C, Ctrl+Z) to the active terminal session.

Safety Considerations

When using iterm-mcp, keep these safety tips in mind:

• You are responsible for monitoring the terminal activity
• The server has no built-in restrictions on what commands can be executed
• Start with smaller, focused tasks until you're comfortable with how the model interacts with your terminal
• Be prepared to interrupt the model if it attempts actions you didn't intend

Practical Examples

Here's how a typical interaction might work:

1. Start iTerm2 and navigate to your desired directory
2. In Claude Desktop, enable the iterm-mcp server
3. Ask Claude to perform a task, such as "Check the disk usage in my current directory"

The model will be able to:

• Run commands like du -h to check disk usage
• Read the terminal output to understand the results
• Format and explain the findings back to you

For interactive sessions like REPLs, the model can also use control characters to navigate or exit the session as needed.

AI: This MCP server provides seamless integration with your iTerm terminal sessions, allowing AI models to interact with your terminal while efficiently managing token usage. The server gives models the ability to view selected terminal output and execute commands in your existing iTerm sessions.

Installation

Setup for Claude Desktop

To integrate with Claude Desktop, you'll need to add the server configuration to your Claude Desktop config file:

On macOS:

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

On Windows:

%APPDATA%/Claude/claude_desktop_config.json

Add the following configuration to the file:

{
  "mcpServers": {
    "iterm-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "iterm-mcp"
      ]
    }
  }
}

Automated Installation via Smithery

For a simpler installation process, you can use Smithery to automatically set up iterm-mcp:

npx -y @smithery/cli install iterm-mcp --client claude

Requirements

Before using iterm-mcp, ensure you have:

• iTerm2 installed and running
• Node.js version 18 or greater

Usage

Available Tools

The iterm-mcp server provides three main tools that models can use to interact with your terminal:

• write_to_terminal - Sends text or commands to your active iTerm terminal window. It returns the number of lines of output produced by the command.

• read_terminal_output - Retrieves a specified number of lines from the active iTerm terminal, allowing the model to see terminal output.

• send_control_character - Sends control characters (like Ctrl+C, Ctrl+Z) to the active terminal session.

Safety Considerations

When using iterm-mcp, keep these safety tips in mind:

• You are responsible for monitoring the terminal activity
• The server has no built-in restrictions on what commands can be executed
• Start with smaller, focused tasks until you're comfortable with how the model interacts with your terminal
• Be prepared to interrupt the model if it attempts actions you didn't intend

Practical Examples

Here's how a typical interaction might work:

1. Start iTerm2 and navigate to your desired directory
2. In Claude Desktop, enable the iterm-mcp server
3. Ask Claude to perform a task, such as "Check the disk usage in my current directory"

The model will be able to:

• Run commands like du -h to check disk usage
• Read the terminal output to understand the results
• Format and explain the findings back to you

For interactive sessions like REPLs, the model can also use control characters to navigate or exit the session as needed.

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.