---
title: "Kilobat with any MCP client: stdio command and mcpServers JSON | Kilobat"
url: "https://kilobat.app/agents/mcp-client.html"
description: "Run Kilobat's Mac network MCP server in any client that supports local stdio servers: the command, the mcpServers JSON, its 43 tools and safety rules."
---

Agent setup

# Kilobat with any MCP client

Kilobat's MCP server is a local stdio command, `kilobat mcp`. Any client that starts local servers can use it, with no API key and no open port.

Free CLI and MCP server · macOS 14 or later · Checked: 30 October 2026

## Install the CLI

The Kilobat CLI is free and open source, and it includes the MCP server. Install it with Homebrew:

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

Check it with `kilobat --version`. `kilobat doctor` says whether the Kilobat app is running, its network filter is on and Pro is active; the tools work without the app, which adds Wi-Fi names, history and rule enforcement. The CLI needs macOS 14 or later.

## Connect the MCP server

1. Point your client at this command. It speaks MCP over stdin and stdout.

   ```
   kilobat mcp
   ```
2. Most clients read an `mcpServers` object like this one:

   ```
   {
     "mcpServers": {
       "kilobat": {
         "command": "kilobat",
         "args": [
           "mcp"
         ]
       }
     }
   }
   ```
3. Grok Build CLI, for example, adds it with one command:

   ```
   grok mcp add kilobat -- kilobat mcp
   ```

An app opened from the Dock doesn't always see the PATH your shell uses. If the server doesn't start, replace `kilobat` with the full path that `command -v kilobat` prints: `/opt/homebrew/bin/kilobat` on Apple silicon, `/usr/local/bin/kilobat` on Intel.

The server has 43 tools with full annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) and returns the same JSON as the CLI. The [docs](https://kilobat.app/docs.html#agents) list every tool.

## Add the skills

Nine Agent Skills teach the agent to read Kilobat's measurements and to ask before changing settings. Install them with [skills.sh](https://skills.sh/seifip/kilobat-skills), which asks which agents to install them for:

```
npx skills add seifip/kilobat-skills
```

For a client that skills.sh doesn't know, copy the folders from [github.com/seifip/kilobat-skills](https://github.com/seifip/kilobat-skills) to where it reads skills. Each skill is a folder with a `SKILL.md`.

The `kilobat` skill is the entry point: it holds the setup and safety rules and sends the agent to the skill that fits, such as `mac-network-troubleshooting` or `mac-agent-runs`. See [all nine skills](https://kilobat.app/docs.html#network-troubleshooting-skill).

## Try these prompts

Ask in plain words. The agent picks the tools; these are the ones each request usually needs.

| Ask | MCP tools |
|---|---|
| The internet feels slow. Find out why and tell me what to fix first. | `diagnose_network`, `get_status` |
| The Wi-Fi is weak in this room. Is the channel crowded, and which one should the router use? | `get_wifi`, `scan_wifi`, `suggest_wifi_channel` |
| npm install hangs on registry.npmjs.org. Find the layer that fails. | `diagnose_connection` |
| What used my hotspot data today, app by app? | `get_usage_report`, `get_status` |
| My video calls stutter even though speed tests look fine. Check for latency spikes. | `run_stutter_test`, `get_nearby_radios` |
| I'm on my phone's hotspot. Which updaters would Kilobat pause, and should I turn that on? | `get_conditions`, `get_updaters`, `set_updater_pause` |
| Which apps are waiting for approval to connect, and who signed them? | `list_approvals` |

## What the agent can and can't change

Kilobat's MCP server marks every tool as read-only or as a change, and each change tool's description tells the agent to get your confirmation first. The [kilobat skill](https://github.com/seifip/kilobat-skills/tree/main/skills/kilobat) holds the same rule: read freely, ask before changing.

### Runs without asking

- Measure Wi-Fi, router, internet and DNS latency, and per-app traffic: `diagnose_network`, `get_status`, `get_wifi`, `scan_wifi`.
- Find the layer that stops one host, trace a route and compare resolvers: `diagnose_connection`, `trace_route`, `benchmark_dns`.
- Read history, sessions, rules and approvals: `get_usage_report`, `list_sessions`, `list_rules`, `list_approvals`.
- Ping for latency spikes with `run_stutter_test`, which sends pings only.

### Asks you first

- A speed test, which uses up to 80 MB (`run_speedtest`; on a metered network, 10 MB or less), and a five-second LAN test (`run_lan_test`).
- Looking up your public IP with Cloudflare (`get_exit_path` with `public_ip`).
- Profiles, app rules, blocked hosts, the new-app mode, budgets, quotas, a network's data cost and pausing updaters (`set_profile`, `set_app_rule`, `block_destination`, `set_new_app_mode`, `set_budget`, `set_app_quota`, `set_network_cost`, `set_updater_pause`).
- DNS, which macOS also guards with an administrator password prompt (`set_dns`).
- Keeping the Mac running with the lid closed, every time (`keep_awake` with `lid_closed`). A plain `keep_awake` changes no settings and ends when it expires.

### Can't do

- Let a waiting app connect on its own: `decide_approval` can block at once, but allowing opens Kilobat's approval window for you to confirm.
- Change AirDrop visibility: `set_airdrop_visibility` opens System Settings for you.
- Change sleep settings, another app's settings, or anything outside Kilobat. It never reads prompts or replies.
- Enforce rules without the Kilobat app and its network filter (Pro). Without them, rules are saved, not applied, and the agent should say so.

Keep your client's confirmation on for the change tools; never auto-approve them.

If the agent can also run shell commands, the `kilobat` CLI can do what the MCP tools do. The skills tell it which commands to run freely and which to ask about.

## Track agent runs

An agent with its own hooks can tell Kilobat when a run starts, waits for you or is done by calling `kilobat agent-event start|working|waiting|done|failed --agent <name> --session <id> --cwd <folder>`. It prints nothing and always exits 0, so it can't break the agent; add `--verbose` when you try it by hand. Ready-made hooks exist for [Claude Code](https://kilobat.app/agents/claude-code.html#hooks), [Codex](https://kilobat.app/agents/codex.html#hooks), [Gemini CLI](https://kilobat.app/agents/gemini-cli.html#hooks) and [Cline](https://kilobat.app/agents/cline.html#hooks). Without hooks, Kilobat goes by the agent's traffic and CPU.

## Sources

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [xAI docs: MCP servers in Grok Build](https://docs.x.ai/build/features/mcp-servers)
- [Kilobat docs: AI agents and MCP](https://kilobat.app/docs.html#agents)
- [skills.sh: supported agents and their skill folders](https://github.com/vercel-labs/skills/blob/main/docs/agents.md)

Checked on 30 October 2026. Agents change their settings often; if a step no longer matches, tell us at the support address.

## Other agents

- [Claude Code](https://kilobat.app/agents/claude-code.html): Give Claude Code your Mac's network as tools: per-app traffic, Wi-Fi, DNS, why a host fails and keep-awake.
- [Codex CLI](https://kilobat.app/agents/codex.html): Codex can check the network before a big download, find why its own request hangs and keep the Mac awake for a long task.
- [Cursor](https://kilobat.app/agents/cursor.html): Let Cursor's agent see why a package download hangs, which app is using the connection and whether the network is metered before a big pull.
- [Gemini CLI](https://kilobat.app/agents/gemini-cli.html): Gemini CLI can diagnose the Mac's network, scan Wi-Fi and keep the Mac awake while it works.
- [Claude Desktop](https://kilobat.app/agents/claude-desktop.html): Ask Claude why the Wi-Fi is slow, what used your hotspot data or whether your VPN carries everything, and it reads the answer from your Mac.
- [Windsurf](https://kilobat.app/agents/windsurf.html): Cascade can find why a dependency won't download, check DNS and trace a route from your Mac, with Kilobat's MCP server.
- [Cline](https://kilobat.app/agents/cline.html): Cline can check the Mac's network and keep it awake while it works.
- [Zed](https://kilobat.app/agents/zed.html): Zed's agent can measure the Mac's network, trace a route and compare DNS resolvers through Kilobat's MCP server.