---
title: "Claude Code의 Kilobat: MCP 서버, 스킬 및 훅 | Kilobat"
url: "https://kilobat.app/ko/agents/claude-code"
description: "claude mcp add로 Kilobat의 Mac 네트워크 MCP 서버를 Claude Code에 추가하고 에이전트 스킬을 설치한 다음 훅을 연결해 Kilobat이 각 실행을 확인하도록 하세요."
---

에이전트 설정

# Claude Code에 Kilobat 설정하기

Claude Code에서 Mac의 네트워크를 도구로 사용하세요. 앱별 트래픽, Wi-Fi, DNS, 호스트 연결 실패 원인과 잠자기 방지를 이용할 수 있습니다. 훅은 실행이 작업 중인지, 입력을 기다리는지, 완료했는지 Kilobat에 알려줍니다.

무료 CLI 및 MCP 서버 · macOS 14 이상 · 확인일: 2026년 10월 30일

## CLI 설치

Kilobat CLI는 무료 오픈 소스이며 MCP 서버를 포함합니다. Homebrew로 설치하세요.

```
brew install seifip/kilobat/kilobat
```

`kilobat --version`로 확인하세요. `kilobat doctor`는 Kilobat 앱이 실행 중인지, 네트워크 필터가 켜져 있는지, Pro가 활성화되어 있는지 알려줍니다. 도구는 앱 없이도 작동하며 앱을 사용하면 Wi-Fi 이름, 기록 및 규칙 적용 기능이 추가됩니다. CLI에는 macOS 14 이상이 필요합니다.

## MCP 서버 연결

확인하려는 Mac에서 에이전트 백엔드와 Kilobat을 실행하세요. 클라우드 러너, Linux 서버 또는 컨테이너는 이 로컬 명령으로 Mac을 검사할 수 없습니다.

1. 모든 프로젝트에 서버를 추가하세요. `--`는 Claude Code 옵션과 실행할 명령을 구분합니다.

   ```
   claude mcp add --scope user kilobat -- kilobat mcp
   ```
2. 새 세션을 시작하고 `/mcp`를 실행하세요. Kilobat이 연결된 상태로 표시됩니다.

`--scope user`가 없으면 서버가 현재 프로젝트의 `~/.claude.json`에만 추가됩니다. `--scope project`를 사용하면 프로젝트의 `.mcp.json`에 추가되어 팀과 공유할 수 있습니다.

## 스킬 추가

9개의 Agent Skills는 에이전트가 Kilobat의 측정값을 읽고 설정을 변경하기 전에 묻도록 알려줍니다. [skills.sh](https://skills.sh/seifip/kilobat-skills)를 사용해 모든 프로젝트에 설치하세요.

```
npx skills add seifip/kilobat-skills -g -a claude-code
```

이렇게 하면 `~/.claude/skills/`에 설치됩니다. `-g`를 생략하면 현재 프로젝트에만 설치되며, 두 플래그를 모두 생략하면 목록에서 에이전트를 선택할 수 있습니다.

`kilobat` 스킬이 진입점입니다. 설정 및 안전 규칙을 담고 있으며 `mac-network-troubleshooting` 또는 `mac-agent-runs`처럼 적합한 스킬로 에이전트를 안내합니다. [9개 스킬 전체](https://kilobat.app/ko/docs/agents#network-troubleshooting-skill)를 확인하세요.

## 이 프롬프트를 사용해 보세요

일상적인 말로 요청하세요. 에이전트가 도구를 선택합니다. 아래는 각 요청에 일반적으로 필요한 도구입니다.

| 묻기 | MCP 도구 |
|---|---|
| 인터넷이 느린 것 같습니다. 이유를 찾아서 무엇부터 고쳐야 할지 알려주세요. | `diagnose_network`, `get_status` |
| npm install이 registry.npmjs.org에서 멈춥니다. 문제가 발생한 계층을 찾아주세요. | `diagnose_connection` |
| 6 GB Docker 이미지를 다운로드하려고 합니다. 지금 해도 좋을까요, 아니면 데이터 제한 네트워크에 연결되어 있나요? | `get_conditions` |
| 전체 테스트를 실행하는 동안 앞으로 두 시간 동안 Mac의 잠자기를 방지하고, 끝나면 해제하세요. | `keep_awake`, `release_awake` |
| 오늘 에이전트 실행이 완료되었나요? 멈추거나 네트워크 연결이 끊어진 실행이 있나요? | `list_sessions` |
| 어떤 항목이 데이터를 많이 업로드하고 있습니다. 어떤 앱이며 지난 한 시간 동안 얼마나 전송했나요? | `get_status`, `get_app_bandwidth` |
| 속도 테스트 결과는 괜찮은데 영상 통화가 끊깁니다. 지연 시간이 급증하는지 확인해 주세요. | `run_stutter_test`, `get_nearby_radios` |

## Claude Code가 변경할 수 있는 항목과 변경할 수 없는 항목

Kilobat의 MCP 서버는 모든 도구를 읽기 전용 또는 변경 도구로 표시하며, 각 변경 도구의 설명에는 에이전트가 먼저 확인을 받도록 안내합니다. [kilobat 스킬](https://github.com/seifip/kilobat-skills/tree/main/skills/kilobat)에도 같은 규칙이 있습니다. 읽기는 자유롭게 하고 변경 전에는 묻습니다.

### 읽기 전용 측정

- Wi-Fi, 라우터, 인터넷 및 DNS 지연 시간과 앱별 트래픽 측정: `diagnose_network`, `get_status`, `get_wifi`, `scan_wifi`.
- 특정 호스트를 막는 계층을 찾고, 경로를 추적하고, 리졸버 비교: `diagnose_connection`, `trace_route`, `benchmark_dns`.
- 기록, 세션, 규칙 및 승인 읽기: `get_usage_report`, `list_sessions`, `list_rules`, `list_approvals`.
- 에이전트와 실행한 명령이 접속한 모든 호스트를 바이트 및 플래그와 함께 확인: `agent_network_log`.
- `run_stutter_test`로 지연 시간 급증을 확인합니다. 이 도구는 ping만 전송합니다.

### 먼저 확인하는 작업

- 최대 80 MB를 사용하는 속도 테스트(`run_speedtest`, 데이터 제한 네트워크에서는 10 MB 이하)와 5초 LAN 테스트(`run_lan_test`).
- Cloudflare로 공인 IP 조회(`public_ip`를 사용하는 `get_exit_path`).
- 프로필, 앱 규칙, 차단된 호스트, 새 앱 모드, 데이터 한도, 할당량, 네트워크의 데이터 비용 및 업데이터 일시 정지(`set_profile`, `set_app_rule`, `block_destination`, `set_new_app_mode`, `set_budget`, `set_app_quota`, `set_network_cost`, `set_updater_pause`).
- 더 좋은 네트워크에 연결할 때까지 Dropbox 같은 다른 앱의 업로드 보류(`hold_upload`).
- DNS 변경. macOS에서도 관리자 암호를 요청하여 보호합니다(`set_dns`).
- 덮개를 닫은 상태에서 Mac을 계속 실행할 때마다 확인합니다(`lid_closed`를 사용하는 `keep_awake`). 일반 `keep_awake`는 설정을 변경하지 않으며 시간이 만료되면 종료됩니다.

### 할 수 없는 작업

- 대기 중인 앱이 자동으로 연결되도록 허용: `decide_approval`는 즉시 차단할 수 있지만 허용하려면 Kilobat의 승인 창이 열려 직접 확인해야 합니다.
- AirDrop 공개 범위 변경: `set_airdrop_visibility`는 시스템 설정을 엽니다.
- 잠자기 설정, 다른 앱의 설정 또는 Kilobat 외부의 항목 변경. 프롬프트나 응답은 읽지 않습니다.
- Kilobat 앱과 네트워크 필터(Pro) 없이 규칙 적용. 이들이 없으면 규칙은 저장되지만 적용되지 않으며 에이전트가 이를 알려야 합니다.

Claude Code는 권한 규칙에서 허용하지 않는 한 MCP 도구를 호출하기 전에 묻습니다. 읽기 작업에서만 확인을 생략하려면 `mcp__kilobat__diagnose_network`처럼 이름으로 도구를 허용하고 Kilobat의 변경 도구는 확인하도록 두세요.

에이전트가 셸 명령도 실행할 수 있다면 `kilobat` CLI로 MCP 도구가 수행하는 작업을 할 수 있습니다. 스킬은 자유롭게 실행할 명령과 먼저 확인할 명령을 알려줍니다.

## 에이전트 실행 추적

이미 있는 훅과 합쳐서 `~/.claude/settings.json`에 추가하세요. 각 훅은 세션 ID와 폴더가 포함된 JSON을 stdin으로 받으며, `--stdin-json`가 이를 읽습니다. 권한 또는 입력 프롬프트는 대기 중을 뜻합니다. Stop은 백그라운드 작업이 끝나면 완료됨을 뜻하고, 속도 제한은 제한이 초기화될 때까지 대기함을 뜻합니다.

```
{
  "hooks": {
    "SessionStart": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent claude --stdin-json" }] }],
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent claude --stdin-json" }] }],
    "Notification": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent claude --stdin-json" }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent claude --stdin-json" }] }],
    "StopFailure": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent claude --stdin-json" }] }],
    "SessionEnd": [{ "hooks": [{ "type": "command", "command": "kilobat agent-event --agent claude --stdin-json" }] }]
  }
}
```

## 출처

- [Claude Code 문서: MCP를 통해 Claude Code를 도구에 연결하기](https://code.claude.com/docs/en/mcp)
- [Claude Code 문서: 훅 참조](https://code.claude.com/docs/en/hooks)
- [Kilobat 문서: AI 에이전트와 MCP](https://kilobat.app/ko/docs/agents#agents)
- [skills.sh: 지원되는 에이전트 및 스킬 폴더](https://github.com/vercel-labs/skills/blob/main/docs/agents.md)

2026년 10월 30일에 확인했습니다. 에이전트 설정은 자주 바뀝니다. 단계가 더 이상 일치하지 않으면 지원 주소로 알려주세요.

## 다른 에이전트

- [Codex CLI](https://kilobat.app/ko/agents/codex): Codex는 대용량 다운로드 전에 네트워크를 확인하고, 자신의 요청이 멈추는 이유를 찾으며, 긴 작업 중 Mac의 잠자기를 방지할 수 있습니다.
- [Cursor](https://kilobat.app/ko/agents/cursor): Cursor 에이전트가 패키지 다운로드가 멈추는 이유와 연결을 사용 중인 앱을 파악하고, 대용량 다운로드 전에 네트워크의 데이터 제한 여부를 확인하도록 하세요.
- [Gemini CLI](https://kilobat.app/ko/agents/gemini-cli): Gemini CLI는 Mac의 네트워크를 진단하고 Wi-Fi를 검색하며 작업 중 Mac의 잠자기를 방지할 수 있습니다.
- [Claude Desktop](https://kilobat.app/ko/agents/claude-desktop): Claude에게 Wi-Fi가 느린 이유, 핫스팟 데이터를 사용한 항목 또는 VPN이 모든 트래픽을 전달하는지 물어보세요. Mac에서 답을 읽어옵니다.
- [Windsurf](https://kilobat.app/ko/agents/windsurf): Cascade는 Kilobat의 MCP 서버를 통해 의존성이 다운로드되지 않는 이유를 찾고, DNS를 확인하고, Mac에서 경로를 추적할 수 있습니다.
- [Cline](https://kilobat.app/ko/agents/cline): Cline은 Mac의 네트워크를 확인하고 작업 중 잠자기를 방지할 수 있습니다.
- [Zed](https://kilobat.app/ko/agents/zed): Zed 에이전트는 Kilobat의 MCP 서버를 통해 Mac의 네트워크를 측정하고 경로를 추적하며 DNS 리졸버를 비교할 수 있습니다.
- [Hermes Agent](https://kilobat.app/ko/agents/hermes): 로컬 MCP 서버를 통해 Hermes Agent에 Mac의 네트워크 측정, 연결 진단 및 잠자기 방지 도구를 제공하세요.
- [OpenClaw](https://kilobat.app/ko/agents/openclaw): 로컬 MCP 도구와 Kilobat 스킬로 OpenClaw가 Mac의 연결 및 데이터 사용량을 확인하도록 하세요.
- [OpenCode](https://kilobat.app/ko/agents/opencode): OpenCode는 Kilobat으로 Mac의 트래픽을 살펴보고 연결 실패를 설명하며 긴 작업 중 잠자기를 방지할 수 있습니다.
- [GitHub Copilot CLI](https://kilobat.app/ko/agents/copilot-cli): Copilot CLI는 Kilobat의 로컬 MCP 서버를 사용해 Mac의 대역폭, DNS 및 다운로드 실패를 확인할 수 있습니다.
- [모든 MCP 클라이언트](https://kilobat.app/ko/agents/mcp-client): Kilobat의 MCP 서버는 로컬 stdio 명령인 kilobat mcp입니다.