iterm-mcp

사용자의 iTerm 세션에 대한 접근을 제공하는 Model Context Protocol (MCP) 서버입니다.

주요 기능 (Features)

효율적인 토큰 사용 (Efficient Token Use): iterm-mcp는 모델이 관심 있는 출력 내용만 검사할 수 있는 능력을 부여합니다. 모델은 일반적으로 실행 시간이 긴 명령의 경우에도 마지막 몇 줄의 출력만 확인하기를 원합니다.

자연스러운 통합 (Natural Integration): iTerm을 모델과 공유합니다. 화면에 무엇이 있는지 질문하거나, 모델에게 작업을 위임하고 모델이 각 단계를 수행하는 과정을 지켜볼 수 있습니다.

전체 터미널 제어 및 REPL 지원 (Full Terminal Control and REPL support): 모델은 REPL과 시작 및 상호작용할 수 있을 뿐만 아니라, ctrl-c, ctrl-z 등과 같은 제어 문자 (control characters)를 보낼 수 있습니다.

가벼운 의존성 (Easy on the Dependencies): iterm-mcp는 최소한의 의존성으로 구축되었으며 npx를 통해 실행할 수 있습니다. Claude Desktop 및 기타 MCP 클라이언트에 쉽게 추가할 수 있도록 설계되었습니다. 별도의 설정 없이 바로 작동해야 합니다.

안전 고려 사항 (Safety Considerations)

• 사용자는 도구를 안전하게 사용하는 것에 대한 책임이 있습니다.
• 내장된 제한 사항 없음: iterm-mcp는 실행되는 명령의 안전성을 평가하려고 시도하지 않습니다.
• 모델은 예상치 못한 방식으로 동작할 수 있습니다. 사용자는 활동을 모니터링하고 적절할 때 중단해야 합니다.
• 다단계 작업의 경우, 모델이 경로를 벗어나면 중단해야 할 수도 있습니다. 모델의 동작 방식에 익숙해질 때까지 작고 집중적인 작업부터 시작하십시오.

도구 (Tools)

• write_to_terminal - 활성화된 iTerm 터미널에 내용을 작성하며, 주로 명령을 실행하는 데 사용됩니다. 명령에 의해 생성된 출력 라인 수를 반환합니다.
• read_terminal_output - 활성화된 iTerm 터미널에서 요청된 줄 수만큼 읽습니다.
• send_control_character - 활성화된 iTerm 터미널로 제어 문자 (control character)를 보냅니다.

요구 사항 (Requirements)

• iTerm2가 실행 중이어야 합니다.
• Node 버전 18 이상

설치 (Installation)

Claude Desktop에서 사용하려면 서버 설정을 추가하세요:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "iterm-mcp": {
...

Smithery를 통한 설치

Smithery를 통해 Claude Desktop용 iTerm을 자동으로 설치하려면 다음 명령어를 실행하세요:

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

개발 (Development)

의존성 설치:

yarn install

서버 빌드:

yarn run build

자동 재빌드(auto-rebuild)를 포함한 개발 모드:

yarn run watch

디버깅 (Debugging)

MCP 서버는 stdio를 통해 통신하므로 디버깅이 어려울 수 있습니다. 패키지 스크립트로 사용할 수 있는 MCP Inspector 사용을 권장합니다:

yarn run inspector
yarn debug <command>

Inspector를 실행하면 브라우저에서 디버깅 도구에 접속할 수 있는 URL이 제공됩니다.