serverhat-macos
Free, open-source Mac menu-bar app that runs your local dev servers. Claude Code and Codex can control them through its MCP server and local API, with your approval. No account, no analytics. By GuruHat.
Install / Use
claude mcp add getguruhat -- npx -y github:getguruhat/serverhat-macosIf the server publishes to npm under a different name, use that package instead — check the repo README.
MCP Server
Model Context Protocol server
Quality Score
Category
Data & AnalyticsSupported Platforms
Our assessment of serverhat-macos
serverhat-macos scores 74/100 on our quality scale, 549th of 604 Data & Analytics skills we index.
Its MCP Server is 16 KB long, well organised into 25 sections with 9 code examples: a thorough specification that gives an agent plenty to work with.
It has 3 GitHub stars, so there is little community track record yet; judge it on its content.
Maintenance, license and trust
- The repository was last updated 4 days ago, so serverhat-macos is actively maintained.
- It is released under the MIT license, a permissive license that allows use, modification and commercial use with attribution.
- Its trust signals score 92/100, with 1 caution from licensing, adoption, age or documentation. These come from repository metadata, not a code audit — read the skill file before letting an agent act on it.
serverhat-macos compared with similar skills
All 4 of these similar skills score higher than serverhat-macos; compare them before choosing.
| Skill | Score | Stars | Updated | Format |
|---|---|---|---|---|
| serverhat-macos (this skill)by getguruhat | 74 | 3 | 4d ago | MCP Server |
| Agent-Reachby Panniantong | 100 | 112.3k | 8d ago | CLAUDE.md |
| rufloby ruvnet | 100 | 81.9k | today | CLAUDE.md |
| headroomby headroomlabs-ai | 100 | 79.8k | today | CLAUDE.md |
| CowAgentby zhayujie | 100 | 48.0k | today | CLAUDE.md |
Frequently asked questions
- How do I install serverhat-macos?
- Run
claude mcp add getguruhat -- npx -y github:getguruhat/serverhat-macos. The install tabs above show the steps for each supported agent. - Which AI agents does serverhat-macos work with?
- It is written for Claude Code, Claude Desktop and OpenAI Codex, as a MCP Server file. Other agents that read the same format can often use it too.
- Is serverhat-macos safe to use?
- It is MIT-licensed and scores 92/100 on trust signals. Skills are instructions an agent will follow, so read the file before installing it and do not approve commands you do not understand.
- Is serverhat-macos still maintained?
- The repository was last updated 4 days ago, so serverhat-macos is actively maintained.
Skill content
View source on GitHubServerHat
Your local web servers, one click away in the Mac menu bar. Free and open source.
No account, no analytics, nothing leaves your Mac.
ServerHat starts, stops, restarts and opens the little web servers you run while you
work (a Node script, npm run dev, python3 -m http.server, anything with a command
line), so you never have to keep a Terminal tab open for them. It also has a local API,
so Claude Code, Codex or your own scripts can add and control servers for you.
<img src="docs/menu.png" width="360" alt="ServerHat's menu: three servers running with their addresses and one stopped"> <img src="docs/menu-dark.png" width="360" alt="The same menu in dark mode">
What it does
- A globe in the menu bar, with a list of your servers. Each shows whether it's starting, ready, unhealthy, stopped, crashed or has its port in use, and has Start/Stop, Restart, Open in browser and View logs. Starting a server from the menu (or allowing one) opens it in your browser once it's up. A running server shows its address as a link. Start all and Stop all are in the Servers row when you have more than one.
- Notices when a server crashes (and shows its last line of output) and when its port is already taken by something else (and which process that is).
- Keeps a log per server, in the app and in
~/Library/Logs/ServerHat/<id>.log. - Stores everything in one readable JSON file and picks up edits to it immediately.
- Exports the server list as JSON, with the option to omit environment values.
- Imports servers from Claude Code's
.claude/launch.json. - Imports a project command from
package.json(dev, orstart), aweb:Procfile entry, or Docker Compose. - Optionally retries a server after a crash, with exponential backoff and a retry limit.
- Runs commands with the same
PATHyour login shell sets up (Homebrew, nvm, and so on), in their own process group, so Stop also ends whatever the server started. - Quitting ServerHat stops the servers it started.
Download
macOS 13 or later, Apple silicon (M1 and newer) only
With Homebrew:
brew install --cask getguruhat/tap/serverhat
Or download ServerHat-<version>-Installer.dmg from the latest release,
open it, and drag ServerHat.app onto Applications.
The app isn't notarized by Apple, so macOS blocks the first launch. Open System Settings › Privacy & Security and click Open Anyway (once). ServerHat is open source: you can read every line or build it yourself.
Windows
The config file
~/Library/Application Support/ServerHat/servers.json:
{
"servers" : [
{
"args" : ["ai-experts/server.mjs"],
"command" : "node",
"cwd" : "~/Developer",
"env" : {},
"id" : "ai-experts",
"name" : "AI Experts",
"port" : 4319,
"startAtLogin" : false,
"url" : "http://127.0.0.1:4319"
}
],
"version" : 1
}
| Field | Required | Meaning |
| --- | --- | --- |
| id | no | Short unique name used by the API and for the log file. Made from name if left out. |
| name | yes | What the menu shows. |
| cwd | no | Folder the command runs in. ~ works. Defaults to your home folder. |
| command | yes | A program on your shell's PATH (node, npm, python3) or a path to one. It is run directly, not through a shell, so no pipes or &&. |
| args | no | Arguments, one string each. |
| port | no | The port the server listens on. ServerHat uses it to detect port conflicts and, without an HTTP URL, to tell "starting" from "running". |
| url | no | What Open in browser opens. Defaults to http://127.0.0.1:<port>. |
| healthContains | no | Optional text that must appear in the configured URL's HTTP response body before ServerHat reports the app ready. |
| env | no | Extra environment variables, {"NAME": "value"}. |
| startAtLogin | no | Start this server whenever ServerHat starts. Turn on Open ServerHat at login (in Settings, the gear in the menu) to have that happen at login. |
| restartOnCrash | no | Retry after an unexpected non-zero exit. Off by default. |
| restartLimit | no | Maximum automatic retries before giving up (1–10, default 3). Delay doubles between attempts, up to 30 seconds. |
Save the file and ServerHat reloads it within a second. If the JSON is broken, the menu says where, and the last good settings stay in use. A server that's running keeps its old settings until you restart it. Removing a server from the file stops it.
Use Settings › Export › Export servers… to save a portable JSON copy. Environment values are omitted by default; choose the separate Export with environment values… action only when you intend to include them, and protect that file accordingly.
Import from .claude/launch.json
Choose + › Import .claude/launch.json… and pick a project folder or its
.claude/launch.json. Each configuration
({name, runtimeExecutable, runtimeArgs, port, url}) becomes a server that runs from the
project folder. Configurations that are already in ServerHat are skipped.
Import a project
Choose + › Import project… and select a project folder. ServerHat prefers the dev
script (or start if there is no dev script) in package.json, a web: command in
Procfile, or a Docker Compose file. It infers a port when the command declares one.
Duplicate commands from the same folder are skipped. The API exposes this as
POST /v1/import-project, and MCP clients can use import_project.
Use it from Claude Code and Codex (MCP)
ServerHat has a built-in MCP server, so AI coding agents get it as tools instead of having to call the API with curl. Open Settings (the gear in the menu), choose Copy for Claude Code (or Copy for Codex) and paste the command into Terminal. It looks like:
<img src="docs/settings.png" width="390" alt="The Settings window: Open ServerHat at login, Copy for Claude Code and Copy for Codex, and Export and Edit servers.json">claude mcp add --scope user serverhat -- /Applications/ServerHat.app/Contents/MacOS/ServerHat --mcp
codex mcp add serverhat -- /Applications/ServerHat.app/Contents/MacOS/ServerHat --mcp
These commands configure the Claude Code CLI and Codex CLI. The matching CLI
must already be installed and available in Terminal's PATH; installing the Claude or
Codex desktop app does not necessarily install its command-line tool. Check with
command -v claude or command -v codex.
To install the CLIs with npm (Node.js is required):
npm install -g @anthropic-ai/claude-code
npm install -g @openai/codex@latest
See the Claude Code setup guide and Codex CLI documentation for other install methods and troubleshooting. After installation, open a new Terminal window, verify the command is found, then run the matching ServerHat setup command above.
The agent then has list_servers, get_server, start_server, stop_server,
restart_server, get_logs, add_server, update_server, remove_server,
import_launch_json and import_project. Start and restart wait until the server is running or has failed,
and a failure comes back with the server's last lines of output. A server an agent adds or
changes waits for you to allow it first (see Approval).
ServerHat --mcp speaks MCP over stdin and stdout and drives the running app through
the API below. It opens ServerHat if it isn't running, and it reads the token from the
token file itself, so the token never goes into an MCP config.
API
ServerHat listens on http://127.0.0.1:47317 (only on this Mac). Change the port with
defaults write com.guruhat.serverhat apiPort -int 47400 and restart ServerHat.
~/Library/Application Support/ServerHat/api.json says where the API is and where its
token is:
{ "url": "http://127.0.0.1:47317", "tokenFile": "~/Library/Application Support/ServerHat/api-token", "configFile": "…/servers.json" }
Security
- Every request except
GET /v1/healthneedsAuthorization: Bearer <token>. The token is created on first launch inapi-token, readable only by you (mode 600, in a folder with mode 700). Delete the file and restart ServerHat to get a new one. - The
Hostheader must be127.0.0.1:<port>orlocalhost:<port>, which blocks DNS rebinding. - Requests that carry an
Originheader, or aSec-Fetch-Siteother thannone, are refused, and CORS preflights are refused, so web pages can't use the API. - Request bodies must be JSON with
Content-Type: application/json, at most 1 MB.
Anyone holding the token can change what ServerHat runs. Keep it out of repositories and logs.
Approval
A server added through the API or MCP, or by editing servers.json, can't start until
you allow it. The same goes for an existing server whose command, args, cwd or
env changes (name, port, url and startAtLogin don't count). ServerHat sends one
notification for each pending command fingerprint; it shows the command and folder, and
clicking it opens Allow, Remove and Later choices. The menu shows the server
with its full command, folder and environment names, and Allow and Remove buttons. Servers you add or edit in ServerHat's own
windows, or import from the menu's + button, count as allowed. So do the servers you
already had when you updated to a version with approvals.
Until you allow it, start and restart answer 403 with an explanation. Add
?wait=<seconds> and they wait that long for you to click Allow, then go ahead. A
server waiting for you has "needsApproval": true in API responses. ServerHat keeps what
you've allowed in its preferences, not in servers.json.
Notifications
ServerHat sends a macOS notification when a server crashes (click it to see the log) and when a server is waiting for your approval (click it to review and allow it). macOS asks for permission the first time. Turn them off in System Settings › Notifications.
Setup for the examples
LW=http://127.0.0.1:47317
TOKEN=$(cat ~/Library/Application\ Support/ServerHat/api-token)
auth=(-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json")
Endpoints
| Method and path | Does |
| --- | --- |
| GET /v1/health | {"ok": true} without a token; shows ServerHat is running. |
| GET /v1/servers | All servers with their status. |
| POST /v1/servers | Add a server. Body: the fields above. Returns it with 201, or 409 if the id is taken. |
| GET /v1/servers/{id} | One server with its status. |
| PATCH /v1/servers/{id} | Change some fields. null clears port or url. |
| PUT /v1/servers/{id} | Replace all fields. |
| DELETE /v1/servers/{id} | Stop and remove a server. |
| POST /v1/servers/{id}/start | Start it. 409 if its port is already in use. |
| POST /v1/servers/{id}/stop | Stop it (SIGTERM to its process group, SIGKILL after 5 s). |
| POST /v1/servers/{id}/restart | Stop it, then start it again. |
| GET /v1/servers/{id}/logs?lines=200 | The last lines of its output (up to 5000), plus the log file path. |
| POST /v1/start-all, POST /v1/stop-all | Start or stop every server. |
| POST /v1/import | Body {"path": "<project folder or launch.json>"}. Returns {"added": [...]}. |
| POST /v1/import-project | Body {"path": "<project folder>"}. Imports a detected local web command. |
| POST /v1/reload | Re-read servers.json now. |
Add ?wait=<seconds> (up to 60) to start, stop and restart to get the answer once the
server is running, stopped or has failed, instead of right away.
Each server in a response has its settings plus:
"status": { "state": "running", "pid": 8101, "startedAt": "2026-10-30T23:06
Truncated for display — read the full file on GitHub.
Related Skills
Agent-Reach
112.3kGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu — one CLI, zero API fees.
ruflo
81.9k🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
headroom
79.8kCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
CowAgent
48.0kOpen-source personal AI assistant & Agent Harness. Plans tasks, runs tools and skills, self-evolves with memory and knowledge. Multi-agent, multi-model, multi-channel. Lightweight, extensible, one-line install.
Languages
Trust signals
From repository metadata: license, adoption, age and documentation. Not a code audit — see the Safety scan above for what the skill file itself contains.
