F
licenseNot graded
qualityD
maintenanceAn MCP server that enables AI agents to control the macOS Terminal.app using AppleScript and the zmx session manager. It allows agents to send keystrokes, type text, and capture screen output in real-time.
iterm-logs-mcp
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@iterm-logs-mcplist my open terminal tabs"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
iterm-logs-mcp
Local MCP server exposing iTerm2 tab/session logs to any MCP-capable agent. Reads terminal
state via AppleScript — the agent decides which tab to read by matching on cwd/job, no
built-in fuzzy-matching logic on the server side.
macOS + iTerm2 only. Local stdio server — not deployed anywhere.
Tools
list_iterm_tabs()— enumerates every open window/tab/session:session_id,window_index,tab_index,name,tty,cwd,job.get_iterm_tab_logs(session_id, max_lines=500)— returns the lastmax_lineslines of scrollback for that session.
Related MCP server: it2mcp
First run
The first AppleScript call against iTerm2 triggers a one-time macOS Automation permission prompt for whichever process runs this script (Terminal, iTerm2, or your MCP client host). Grant it once in System Settings → Privacy & Security → Automation.
Run it
uv run --directory /path/to/iterm-logs-mcp server.pyRegister with Claude Code
claude mcp add iterm-logs -- uv run --directory /path/to/iterm-logs-mcp server.pyRegister with Claude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"iterm-logs": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/iterm-logs-mcp",
"server.py"
]
}
}
}Available Tools
2 toolsget_iterm_tab_logsA
Get scrollback/log contents for one iTerm2 session, identified by the session_id returned from list_iterm_tabs. Returns the last max_lines lines.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| max_lines | No | ||
| session_id | Yes |
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.3/5.0
Behavior3/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses read-only behavior and the return of last max_lines lines, but lacks details about authentication needs, rate limits, or any side effects. The description is transparent but minimal.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, and contains no unnecessary words. It efficiently conveys the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (2 parameters, output schema exists), the description covers the essential information: what it does, how to identify the session, and the meaning of max_lines. It is complete for a tool of this complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so description must compensate. It explains session_id as coming from list_iterm_tabs and max_lines as controlling the number of lines returned. This adds meaning beyond the schema, though more detail could be provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description explicitly states the verb ('get'), the resource ('scrollback/log contents'), and the identifier ('session_id returned from list_iterm_tabs'), clearly distinguishing it from the sibling tool list_iterm_tabs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates the prerequisite of obtaining session_id from list_iterm_tabs and explains the max_lines parameter, providing clear context for usage. However, it does not explicitly state when not to use this tool or offer alternatives beyond the implicit prerequisite.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
list_iterm_tabsA
List every open iTerm2 window/tab/session with its cwd and running job, so the caller can pick which one to read logs from.
ParametersJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
ParametersJSON Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
A4.5/5.0
Behavior4/5
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so the description carries the full burden. It explains the tool lists tabs with cwd and running job, indicating a read-only operation. No side effects or contradictions are mentioned, which is acceptable for a simple list tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Conciseness5/5
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that front-loads the action and includes essential details (cwd, running job). No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Completeness5/5
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has no parameters and an output schema exists (though not shown), the description is complete. It explains what is returned and the purpose, which is sufficient for such a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Parameters4/5
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters, so schema coverage is 100%. The description correctly does not add parameter information as none exist. Baseline 4 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Purpose5/5
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists open iTerm2 windows/tabs/sessions with cwd and running job, and explicitly says the caller can use it to pick which tab to read logs from. This distinguishes it from the sibling tool get_iterm_tab_logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Usage Guidelines4/5
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage before get_iterm_tab_logs by stating 'so the caller can pick which one to read logs from.' It provides context but does not explicitly state when not to use it or alternatives, though the sibling is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
A4.4/5.0
Disambiguation5/5
The two tools have clearly distinct purposes: one lists all open tabs with session IDs, the other retrieves logs for a specific session. There is no overlap or confusion.
Naming Consistency5/5
Both names follow a consistent verb_noun pattern in snake_case: list_iterm_tabs and get_iterm_tab_logs. The naming is clear and predictable.
Tool Count3/5
With only 2 tools, the set is minimal but covers the basic workflow of listing tabs and retrieving logs. However, it feels thin for a server claiming to provide log access, and could benefit from additional filtering or search tools.
Completeness4/5
The tool surface covers the core use case of listing tabs and reading logs. Minor gaps exist, such as no tool for retrieving full logs without a line limit or for searching within logs, but these are not critical.
Maintenance
ActivitySlowing
ResponsivenessSyncing
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Personal assistant MCP server with search, execute, packages, jobs, secrets, and integrations.
MCP connector for iMessage & Contacts via a local Mac agent + Vercel relay
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that enables AI assistants to control iTerm2 sessions, windows, tabs, and profiles using the official iTerm2 Python API. It includes a security model with session tagging and tiered permissions to ensure safe and controlled terminal interactions.401MIT
- AlicenseAqualityCmaintenanceAn MCP server that provides full control over iTerm2 terminal sessions on macOS. It enables users to manage windows, tabs, and panes, run commands, read screen content, and interact with terminal sessions through Claude.18MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that exposes iTerm2 tab control as native tools, designed for the conductor pattern where one Claude/Codex session drives sibling tabs.110MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/kkaustubhvyas/iterm-logs-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server