🚀 Enhanced iTerm MCP Server


Advanced iTerm2 automation with Python API integration - The ultimate terminal control solution for AI assistants.

> ⚡ Now with native Python API - Direct iTerm2 integration for maximum reliability and performance

⚡ Quick Start

$3

#### Via NPM (Recommended) - Now Available!
``bash
npm install -g enhanced-iterm-mcp-server
`

> 🎉 Just Published! The package is now available on NPM registry for easy installation.

#### From Source
`bash
git clone https://github.com/2black0/enhanced-iterm-mcp-server.git
cd enhanced-iterm-mcp-server
npm install
./setup-python-api.sh
npm run build
`

$3

1. Open iTerm2 → Preferences (⌘,)
2. Go to General → Magic
3. Check "Enable Python API"
4. Restart iTerm2

$3

`json
{
"mcpServers": {
"enhanced-iterm": {
"command": "node",
"args": ["/path/to/enhanced-iterm-mcp-server/dist/index-python-api.js"],
"type": "stdio"
}
}
}
`

$3

`bash

If installed globally

enhanced-iterm-mcp test

If installed from source

npm test
`

📦 Installation Methods

$3

`bash

Install globally

npm install -g enhanced-iterm-mcp-server

Use anywhere

enhanced-iterm-mcp --help

Configuration path for Claude Desktop

~/.npm/lib/node_modules/enhanced-iterm-mcp-server/dist/index-python-api.js

`

> ✅ Package is now live on NPM! Install with npm install -g enhanced-iterm-mcp-server

$3


`bash

Install in project

npm install enhanced-iterm-mcp-server

Use with npx

npx enhanced-iterm-mcp --help

Configuration for Claude Desktop

/path/to/project/node_modules/enhanced-iterm-mcp-server/dist/index-python-api.js

`

$3

`bash

Use without installation

npx enhanced-iterm-mcp-server --help

Claude Desktop configuration

{
"mcpServers": {
"enhanced-iterm": {
"command": "npx",
"args": ["enhanced-iterm-mcp-server"],
"type": "stdio"
}
}
}
`

> 🚀 Live on NPM Registry: https://www.npmjs.com/package/enhanced-iterm-mcp-server

🛠 Available Tools

$3

- open-terminal - Create new terminals with profiles and commands
- list-all-sessions - Complete overview of all iTerm2 windows/tabs/sessions

$3

- split-terminal-horizontal / split-terminal-vertical - Split panes with profile support
- execute-command-in-pane - Execute commands in specific panes
- broadcast-input - Send commands to multiple panes simultaneously

$3

- get-session-info - Basic session information and status
- get-session-details - Comprehensive session details with all variables
- monitor-session - Monitor session changes over time

$3

- set-tab-color - Set tab colors (named colors or hex codes)

$3

- list-panes - List tracked panes
- get-terminal-state - Terminal state overview

🎯 Key Features

$3

- Direct access to iTerm2's native Python API
- Real-time session variable monitoring
- Robust error handling with automatic retries
- No AppleScript limitations

$3

- Multi-pane broadcasting for simultaneous commands
- Profile-based terminal creation with custom configurations
- Real-time session monitoring with 10+ variables
- Visual customization with tab coloring

$3

- Comprehensive error handling and logging
- Timeout protection for all operations
- Virtual environment isolation
- Clean TypeScript implementation

📖 Usage Examples

$3

`javascript
// Open new terminal
await callTool("open-terminal", {
command: "htop",
workingDirectory: "/Users/username/projects"
})

// Split horizontally with profile
await callTool("split-terminal-horizontal", {
profile: "Development",
command: "npm run dev"
})
`

$3


`javascript
// Broadcast command to multiple panes
await callTool("broadcast-input", {
paneIds: ["session-1", "session-2", "session-3"],
command: "git status"
})

// Monitor session changes
await callTool("monitor-session", {
paneId: "session-1",
duration: 30
})
`

$3


`javascript
// Get comprehensive session details
await callTool("get-session-details", {
sessionId: "213D676B-19F7-42A4-9E34-B2B81D40105B"
})

// List all active sessions
await callTool("list-all-sessions", {})
`

🔧 Development

$3


`bash
npm run build # Build TypeScript
npm start # Run production
npm run dev # Development mode
`

$3

`bash
npm test # Test tool listing
npm run test-sessions # Test session access
`

🚨 Troubleshooting

$3

- Enable in iTerm2 Preferences → General → Magic → Python API
- Restart iTerm2 after enabling

$3

- Ensure iTerm2 is running
- Check Python virtual environment: source iterm_env/bin/activate
- Verify iterm2 package: pip list | grep iterm2

$3

- Use list-all-sessions to get valid session IDs
- Session IDs change when sessions are closed/reopened

📄 License

ISC License

🙏 Built With

- Model Context Protocol SDK
- iTerm2 Python API
- TypeScript + Node.js

---

🎯 The Ultimate iTerm2 Automation Solution for AI Assistants

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

$3

`bash
git clone https://github.com/2black0/enhanced-iterm-mcp-server.git
cd enhanced-iterm-mcp-server
npm install
./setup-python-api.sh
npm run dev
``

📜 Changelog

See CHANGELOG.md for detailed version history.

🙏 Acknowledgments

- Model Context Protocol by Anthropic
- iTerm2 Python API by George Nachman
- TypeScript community for excellent tooling

⭐ Support

If this project helps you, please consider:
- ⭐ Starring the repository
- 🐛 Reporting issues
- 🔧 Contributing improvements
- 📢 Sharing with others

---

Built with ❤️ for the AI automation community