herdr-mcp

실행 중인 Herdr 터미널 세션을 코딩 에이전트가 제어할 수 있게 해 주는 MCP 서버입니다: 워크스페이스와 탭, 팬, 에이전트를 나열하고, 팬 출력을 읽고, 다른 에이전트에 프롬프트를 보내고, 키를 입력하고, 명령을 실행하며, 상태나 출력을 기다리거나 팬을 분할/닫을 수 있습니다.

이 서버는 가벼운 stdio 브리지입니다. 모든 도구는 herdr CLI를 하위 프로세스로 실행하며, herdr CLI는 이미 Herdr의 소켓 API를 사용해 JSON 응답 형식으로 답합니다. 데몬도, 포트도, 설정 파일도, 인증도 없습니다.

요구사항

• herdr가 설치되어 PATH에 있어야 합니다(또는 HERDR_BIN에 전체 경로를 설정).

• 실행 중인 Herdr 세션이 필요합니다. 이 서버는 herdr CLI가 환경(HERDR_SOCKET_PATH / HERDR_SESSION)에서 확인하는 세션과 통신합니다.

• Python 3.12 이상 및 uv가 필요합니다.

Related MCP server: HT MCP Server

실행

체크아웃에서:

uv run herdr-mcp

GitHub에서 바로, 체크아웃 없이:

uvx --from git+https://github.com/aelaguiz/herdr-mcp herdr-mcp

이 프로세스는 stdio로 MCP를 제공하므로 stdout에는 아무것도 출력하지 않습니다. 로그는 stderr로 기록됩니다(HERDR_MCP_LOG_LEVEL=DEBUG로 argv 추적 가능).

클라이언트 설정

Claude Code:

claude mcp add herdr -- uvx --from git+https://github.com/aelaguiz/herdr-mcp herdr-mcp

일반적인 mcpServers JSON(Claude Desktop, Cursor, Codex 등):

{
  "mcpServers": {
    "herdr": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/aelaguiz/herdr-mcp", "herdr-mcp"],
      "env": {}
    }
  }
}

대신 로컬 체크아웃에서:

{
  "mcpServers": {
    "herdr": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/herdr-mcp", "herdr-mcp"]
    }
  }
}

도구

팬 ID는 w17:p1처럼 보이고, 탭 ID는 w17:t1처럼, 워크스페이스 ID는 w17처럼 보입니다. 에이전트 도구는 팬 ID 또는 에이전트 이름을 받습니다. 모든 도구는 herdr JSON 봉투에서 파싱한 result 객체를 반환합니다. read_pane은 일반 텍스트를 반환합니다.

CLI에서 발생한 실패(알 수 없는 팬, 시간 초과, 사용할 수 없는 소켓)는 herdr 고유의 오류 코드와 메시지를 담은 MCP 도구 오류로 반환되어, 모델이 스스로 교정할 수 있습니다.

보안

인증도, 샌드박스도 없으며 로컬 stdio만 지원합니다. 이 서버를 실행할 수 있는 모든 클라이언트는 터미널 팬에서 임의의 명령을 실행하고 화면에 표시된 모든 것(에이전트 팬이 표시하는 내용 포함)을 읽을 수 있습니다. 반드시 자신의 기기에서 신뢰할 수 있는 클라이언트에만 연결하세요.

환경

환경 변수의 나머지 값은 그대로 전달되며, 이를 통해 CLI가 올바른 세션 소켓을 찾습니다.

개발

uv sync
uv run pytest -q

단위 테스트는 SDK의 인메모리 클라이언트를 통해 스텁 herdr 스크립트를 대상으로 서버를 실행하므로, 실제 실행 중인 세션에는 영향을 주지 않습니다.