https://github.com/ferrislucas/iterm-mcp

A Model Context Protocol server that executes commands in the current iTerm session
https://github.com/ferrislucas/iterm-mcp

ai claude claude-ai mcp mcp-server

Last synced: 21 days ago
JSON representation

A Model Context Protocol server that executes commands in the current iTerm session

• Host: GitHub
• URL: https://github.com/ferrislucas/iterm-mcp
• Owner: ferrislucas
• License: mit
• Created: 2025-01-09T04:49:23.000Z (about 1 month ago)
• Default Branch: main
• Last Pushed: 2025-01-18T02:02:00.000Z (21 days ago)
• Last Synced: 2025-01-18T02:12:29.057Z (21 days ago)
• Topics: ai, claude, claude-ai, mcp, mcp-server
• Language: TypeScript
• Homepage: https://www.npmjs.com/package/iterm-mcp
• Size: 1.18 MB
• Stars: 2
• Watchers: 1
• Forks: 2
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • License: LICENSE.md

Awesome Lists containing this project

• awesome-mcp-servers - ferrislucas/iterm-mcp - iTermへのアクセスを提供するモデルコンテキストプロトコルサーバー。コマンドを実行し、iTermターミナルで見た内容について質問することができます。 (サーバー実装 / 💻 <a name="developer-tools"></a>開発者ツール)

README

        
![Main Image](.github/images/demo.gif)

# iterm-mcp 

A Model Context Protocol server that provides access to your iTerm session.

### Features

- **Efficient Token Use**: Only the visible content of the terminal is passed to the model. The model can retrieve content that's not visible if necessary.

- **Supports Long-Running Processes**: iterm-mcp knows when the terminal is waiting for user input. Long-running processes are handled gracefully.

- **Interrupt When Needed**: Send control characters to the terminal to interrupt processes.

- **Inspect Terminal Activity**: Gives the model visibility into the current terminal content.



### Tools

- `write_to_terminal` - Writes to the active iTerm terminal, often used to run a command.

- `read_terminal_output` - Reads the output from the active iTerm terminal.

- `send_control_character` - Sends a control character to the active iTerm terminal.

## Installation

To use with Claude Desktop, add the server config:

On macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

On Windows: `%APPDATA%/Claude/claude_desktop_config.json`

```json

{

  "mcpServers": {

    "iterm-mcp": {

      "command": "npx",

      "args": [

        "-y",

        "iterm-mcp"

      ]

    }

  }

}

```

### Installing via Smithery

To install iTerm for Claude Desktop automatically via [Smithery](https://smithery.ai/server/iterm-mcp):

```bash

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

```

[![smithery badge](https://smithery.ai/badge/iterm-mcp)](https://smithery.ai/server/iterm-mcp)

## Development

Install dependencies:

```bash

yarn install

```

Build the server:

```bash

yarn run build

```

For development with auto-rebuild:

```bash

yarn run watch

```

### Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which is available as a package script:

```bash

yarn run inspector

yarn debug 

```

The Inspector will provide a URL to access debugging tools in your browser.