repository·main·Indexed 20 days ago
https://github.com/ferrislucas/iterm-mcpA Model Context Protocol (MCP) server that provides LLMs access to the currently active tab of iTerm2. It enables models to run commands via write_to_terminal, read terminal output using read_terminal_output, and send control characters through send_control_character.
If you are contributing to or modifying the iterm-mcp repository, use these commands to manage the development lifecycle:
yarn installyarn run buildyarn run watchTo integrate iterm-mcp with Claude Desktop, you must add the server configuration to your Claude Desktop configuration file.
Config File Locations:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%/Claude/claude_desktop_config.jsonAdd the following entry to the mcpServers object in your JSON configuration:
{
"mcpServers": {
"iterm-mcp": {
"command": "npx",
"args": [
"-y",
"iterm-mcp"
]
}
}
}Before installing, ensure your environment meets these requirements:
You can automatically install iterm-mcp for Claude Desktop using the Smithery CLI by running the following command:
npx -y @smithery/cli install iterm-mcp --client claudeBecause MCP servers communicate over stdio, debugging can be difficult. It is recommended to use the MCP Inspector.
If you are developing the project locally, you can use the following commands to start the inspector and debug a specific command:
yarn run inspector
yarn debug <command>The iterm-mcp server exposes the following tools to the MCP client:
write_to_terminal: Writes to the active iTerm terminal (e.g., to run a command). Returns the number of lines of output produced.read_terminal_output: Reads a specified number of lines from the active iTerm terminal.send_control_character: Sends a control character (like ctrl-c or ctrl-z) to the active iTerm terminal.The write_to_terminal tool allows an MCP client to write text or execute a command in the active iTerm terminal.
Important Note: The tool returns a summary of how many lines were output after the command was sent. It does not return the actual command output or a confirmation of success. You must use the read_terminal_output tool to inspect the results. Never assume a command was executed successfully based solely on this tool's response.
{
"name": "write_to_terminal",
"arguments": {
"command": "ls -la"
}
}The send_control_character tool sends a control character to the active iTerm terminal. This is useful for interrupting processes (e.g., sending Control-C) or sending special escape sequences.
{
"name": "send_control_character",
"arguments": {
"letter": "C"
}
}The read_terminal_output tool reads the recent output from the active iTerm terminal. This is the primary way to inspect the results of commands sent via write_to_terminal.
{
"name": "read_terminal_output",
"arguments": {
"linesOfOutput": 50
}
}The iterm-mcp server exposes the following tools via the Model Context Protocol:
{
"tools": [
{
"name": "write_to_terminal",
"description": "Writes text to the active iTerm terminal - often used to run a command in the terminal",
"inputSchema": {
"type": "object",
"properties": {
"command": {
"type": "string",
"description": "The command to run or text to write to the terminal"
}
},
"required": ["command"]
}
},
{
"name": "read_terminal_output",
"description": "Reads the output from the active iTerm terminal",
"inputSchema": {
"type": "object",
"properties": {
"linesOfOutput": {
"type": "integer",
"description": "The number of lines of output to read."
}
},
"required": ["linesOfOutput"]
}
},
{
"name": "send_control_character",
"description": "Sends a control character to the active iTerm terminal (e.g., Control-C, or special sequences like ']' for telnet escape)",
"inputSchema": {
"type": "object",
"properties": {
"letter": {
"type": "string",
"description": "The letter corresponding to the control character (e.g., 'C' for Control-C, ']' for telnet escape)"
}
},
"required": ["letter"]
}
}
]
}