MCP 서버로 쓰기

butler mcp serve로 Butler를 다른 MCP 클라이언트에 연결합니다.

이 페이지

butler mcp serve를 실행하면 Butler가 MCP 서버로 동작합니다. MCP를 지원하는 다른 클라이언트에서 Butler의 상태, 작업 기록, 기억 그래프, 스킬 목록을 도구로 불러 쓸 수 있습니다.

이 기능은 standalone Butler Agent의 CLI로 실행합니다. 먼저 Butler Agent CLI를 따라 Agent를 설치합니다.

연결하기

설치한 butler의 절대 경로를 확인합니다. 설치 스크립트를 그대로 썼다면 ~/.local/opt/butler-agent/<버전>/butler입니다.
MCP 클라이언트의 서버 설정에 Butler를 추가합니다. 명령은 butler의 절대 경로, 인자는 mcp serve입니다.
클라이언트에서 서버를 다시 불러온 뒤 Butler 도구 8개가 보이는지 확인합니다.

클라이언트 설정 예시

mcpServers 형식을 쓰는 클라이언트라면 다음과 같이 설정합니다. 경로는 실제 사용자 이름과 설치 버전에 맞게 바꿉니다.

json

{
  "mcpServers": {
    "butler": {
      "command": "/Users/me/.local/opt/butler-agent/0.0.21/butler",
      "args": ["mcp", "serve", "--data", "/Users/me/.butler"]
    }
  }
}

command: 클라이언트는 셸을 거치지 않고 실행하므로 ~ 없이 절대 경로로 적습니다.
args: mcp serve는 필수입니다. --data는 생략할 수 있습니다.

--data 대신 env에 BUTLER_DATA를 넣어도 됩니다.

json

{
  "mcpServers": {
    "butler": {
      "command": "/Users/me/.local/opt/butler-agent/0.0.21/butler",
      "args": ["mcp", "serve"],
      "env": { "BUTLER_DATA": "/Users/me/.butler" }
    }
  }
}

터미널에서 확인하기

bash

butler mcp serve --data ~/.butler

실행하면 클라이언트의 입력을 기다리며 멈춰 있습니다. 정상 동작입니다. CtrlC로 종료합니다.

옵션

항목	설명
연결 방식	표준 입출력(stdio)만 지원합니다. HTTP 같은 다른 연결 방식은 없습니다.
`--data PATH`	사용할 데이터 폴더입니다. `~/`로 시작하는 경로도 받습니다.
`BUTLER_DATA`	`--data`가 없을 때 쓰는 데이터 폴더입니다. 둘 다 없으면 `~/.butler`를 씁니다.
서버 이름	데이터 폴더의 `butler.config.json`에 있는 `system.mcpServerName` 값을 서버 이름으로 알립니다. 값이 없으면 `butler-main`입니다.

지원하지 않는 옵션을 붙이면 unsupported MCP option 오류로 종료합니다.

제공하는 도구

Butler MCP 서버는 도구(tools)만 제공합니다. 리소스와 프롬프트는 제공하지 않습니다.

조회 도구

도구	설명
`butler_status`	서비스 가동 시간, 모델 상태, 작업 통계(전체, 실행 중, 완료, 실패), hot cache 파일 수를 보여 줍니다.
`list_tasks`	작업 목록을 보여 줍니다. 선택 인자 `status`에 `RUNNING`, `DONE`, `FAILED`, `PENDING` 중 하나를 넣어 걸러 볼 수 있습니다.
`get_task_result`	필수 인자 `task_id`로 작업 하나의 요청과 전체 결과를 보여 줍니다.
`project_list`	프로젝트별 작업 수와 최근 작업을 보여 줍니다.
`memory_graph`	프로젝트, 결정, 도구, 사람 사이의 관계 그래프를 검색합니다. 인자는 아래 표를 참고합니다.
`skill_list`	불러온 스킬과 설명을 보여 줍니다.

memory_graph는 다음 인자를 받습니다.

인자	필수	설명
`query`	예	찾을 엔티티 이름이나 키워드입니다.
`type`	아니요	`project`, `person`, `concept`, `decision`, `tool`, `interest` 중 하나로 걸러 봅니다.
`hops`	아니요	따라갈 관계 단계 수입니다. 1에서 4까지이며 기본값은 2입니다.
`project`	아니요	특정 프로젝트의 결과만 봅니다.

변경 도구

도구	설명
`model_set`	Worker 모델과 Butler 모델을 조회하거나 바꿉니다. 인자는 모두 선택입니다. `target`(`worker` 또는 `butler`)과 `model`을 넣으면 해당 모델을 바꾸고, `model`을 비우면 현재 설정을 보여 줍니다. `action`에 `list`를 넣으면 쓸 수 있는 모델 별칭을 보여 줍니다. Butler 모델 변경은 다음 재시작부터 적용됩니다.
`restart_butler`	같은 DATA 폴더의 Agent 서비스를 다시 시작합니다.

동작 방식

butler mcp serve는 Agent 서비스를 시작하지 않습니다. 데이터 폴더에 저장된 기록과 설정을 읽어 답합니다. 서비스가 실행 중이 아니면 butler_status의 가동 시간은 unknown으로 나옵니다.
시작할 때 데이터 폴더의 tasks에서 30일이 지난 완료(DONE)·실패(FAILED) 작업 기록을 지웁니다. 남은 기록이 100개를 넘으면 오래된 완료·실패 기록부터 지웁니다.
표준 출력은 MCP 메시지에만 씁니다. 시작 메시지와 오류는 표준 오류로 출력합니다.

주의 사항

설정과 서비스를 바꾸는 도구

model_set은 설정 파일을 바꾸고, restart_butler는 Agent 서비스를 다시 시작합니다. Butler 앱과 같은 DATA 폴더를 쓰면 앱이 실행한 Agent도 이 도구의 영향을 받습니다. 클라이언트에서 도구 호출 전에 확인을 받도록 설정하기를 권장합니다.

HOME 환경 변수가 없으면 시작하지 못하고 native_home_unavailable 오류를 냅니다. 클라이언트가 환경 변수를 비운 채 실행한다면 env에 HOME을 추가합니다.

연결하기

클라이언트 설정 예시

터미널에서 확인하기

옵션

제공하는 도구

조회 도구

변경 도구

동작 방식

주의 사항

관련 문서