homeshed-mcp 0.1.2

Every tool your AI needs, in one install: memory, reasoning, git, Docker and more.

A self-hosted MCP server for Claude Code, Claude Desktop, Cursor, VS Code, OpenCode and any MCP client.
Your model first, the cloud when you choose.

Install · What your AI can do · All tools · Security · Compare · Roadmap · Pro · FAQ

HomeShed is a self-hosted Model Context Protocol tool server. Add it to your AI assistant and it can check your containers, work with git, remember what it learned across sessions, spot bugs it has seen before, and solve logic problems: 119 tools behind one endpoint that you run and control.

_{The optional Control Panel on a fresh install. HomeShed itself runs without it.}

Why people use it

Free and open source (Apache-2.0). One install, 119 tools, no account, no GPU.

• Memory that carries across sessions. Your AI remembers facts, decisions and fixes between conversations and across projects. It's built in, with nothing extra to run. Facts are kept by category and recalled by relevance to the task in hand, and in Claude Code each project gets its own memory automatically.
• Finds the API keys your AI has already seen. Claude Code keeps every conversation on disk as plain text, including any key that was pasted or printed. HomeShed checks those files and tells you which kinds of key are there, where, and where to rotate them, without showing the keys themselves.
• Reasoning where language models slip. A logic and constraint solver (Z3) handles the puzzles models get wrong, big tasks break into steps, and a router says when a task needs a frontier model and when a smaller one will do.
• Your model first, the cloud when you choose. Routine work like drafts and summaries can go to a model you run (Ollama, llama.cpp, LM Studio) or to cloud keys you bring. HomeShed doesn't include a model or need a GPU.
• Ready-to-publish checks for your own projects. What a professional repository needs, private details and secrets caught before they go public, docs checked against the code, and a progress score. They're the checks used to prepare this release.
• Mistakes that stay fixed. Your AI logs corrections and broken rules as observations, repeats get flagged, and a known-bugs list answers "has this error been seen before?"
• Checks before your AI acts. Rule packs check each command and file write before Claude Code runs it, and stop risky ones with the reason and what to do instead. Write your own in a few lines of JSON, or add HomeShed Pro's curated packs (how).
• A Control Panel, if you want one. An optional web page on your own machine shows what's running and what it has saved you, with a switch for every tool and a key for every app. Add it any time; HomeShed never needs it.
• One endpoint, you stay in control. Every app gets its own key, tool list and rate limit, and every change to them is logged. Tools that act on your machines start off, and keys sit in an encrypted vault that's never shown to the AI.

Install

A real run, from setup to the first answers:

Three steps. No accounts, no keys, no GPU.

1. Install uv (the tool that runs homeshed-mcp; once per computer). Open a terminal (Windows: press Start, type PowerShell, press Enter; macOS: open Terminal) and paste:

Then close the terminal and open a new one, so it can find uv. uvx --version prints a version number when it's ready.

2. Add it to your AI app. For Claude Code (already installed), one command finds a local model if you run one, lists the optional tool groups (the ones it finds are ticked: press Enter to keep them), then asks before adding HomeShed (answer Y):

uvx homeshed-mcp setup

For Cursor, VS Code or Claude Desktop, click the button for your app (Claude Desktop's downloads homeshed-mcp.mcpb: double-click that file). Or add it to Claude Code yourself:

claude mcp add -s user homeshed-mcp -- uvx homeshed-mcp

3. Quit your app fully, open it again, and try it in its chat (Windows: right-click its icon by the clock and choose Quit; macOS: Cmd+Q; Cursor and VS Code: use agent mode). These work straight away, with nothing else set up:

• "What tools do you have from homeshed-mcp?"
• "What are github.com's IP addresses?"
• "Is port 443 open on example.com?"
• "Use the logic solver: which whole numbers x and y give x + y = 10 and x − y = 4?"
• "What operating system and CPU is this machine running?"

Stuck? If the terminal says uvx isn't recognised or not found, open a new terminal and try again. Then run uvx homeshed-mcp doctor: it checks everything and gives you the exact command to fix anything that's missing. If your app can't start uvx (common for apps opened from the macOS Dock), put the full path that which uvx prints into its MCP settings in place of uvx.

{
  "mcpServers": {
    "homeshed-mcp": {
      "command": "uvx",
      "args": [
        "homeshed-mcp"
      ]
    }
  }
}

{
  "servers": {
    "homeshed-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "homeshed-mcp"
      ]
    }
  }
}

{
  "context_servers": {
    "homeshed-mcp": {
      "source": "custom",
      "command": "uvx",
      "args": [
        "homeshed-mcp"
      ]
    }
  }
}

{
  "mcp": {
    "homeshed-mcp": {
      "type": "local",
      "command": [
        "uvx",
        "homeshed-mcp"
      ],
      "enabled": true
    }
  }
}

extensions:
  homeshed-mcp:
    type: stdio
    name: homeshed-mcp
    enabled: true
    cmd: uvx
    args: [homeshed-mcp]
    timeout: 300

[mcp_servers.homeshed-mcp]
command = "uvx"
args = ["homeshed-mcp"]

claude mcp add -s user homeshed-mcp -e LOCAL_AI_BASE_URL=http://localhost:11434/v1 -- uvx homeshed-mcp

New to terminals? Follow the step-by-step guide: every step explained, with what you should see after each one.

Run it as a server for all your apps (Docker)

Run it once and connect every assistant, agent and machine to it, each with its own key, grants and limits.

On the server (it needs Docker, and uv from step 1 above):

git clone https://github.com/keefng8/homeshed-mcp.git && cd homeshed-mcp
uvx homeshed-mcp init               # writes .env here (token, vault key, allowed hosts) and prints your owner token once
docker compose up -d                 # listens on 127.0.0.1:8765

Then, on the machine where your AI app runs (the same machine here):

claude mcp add -s user --transport http homeshed-mcp http://127.0.0.1:8765/mcp --header "Authorization: Bearer YOUR_TOKEN"

Replace YOUR_TOKEN with the token init printed. The server keeps its copy in .env (git ignores it; back it up, since init shows the token only once). On the app's side, keep the token in an environment variable rather than a file you might share: to share the setup with a team, commit a .mcp.json that names the variable ("Authorization": "Bearer ${MCP_TOKEN}"), never the token itself. To connect from other machines, see configuration.

Add the Control Panel (optional)

A web page for your install, on your own machine: see at a glance what's running and what it has saved you, switch any tool off, give each app its own key, and keep your keys encrypted in one place. HomeShed never needs it. Add it now, later, or not at all, and remove it without touching HomeShed.

With Docker, in the HomeShed folder:

docker compose --profile panel up -d
docker compose logs panel            # the first-run password, printed once

Without Docker, in the folder where you ran uvx homeshed-mcp init:

uvx homeshed-mcp serve --http                         # HomeShed as a server; leave it running
uvx --from "homeshed-mcp[panel]" homeshed-mcp panel   # in a second terminal

Then open http://127.0.0.1:9090 and sign in. The panel answers on this machine only and always asks for a password. Every page says Not set up yet, and what it needs, for anything you haven't added. More: the panel's README and its page-by-page guide.

What your AI can do

flowchart LR
    C["Claude Code · Claude Desktop<br/>Cursor · VS Code · any MCP client"] -- "one endpoint" --> R["HomeShed<br/>keys · grants · limits · audit"]
    R --> T["Built-in tools<br/>memory · git · files · network · logic solver · workflows"]
    R -. "if you run one" .-> L["Your model<br/>Ollama · llama.cpp · LM Studio"]
    R -. "your keys" .-> K["Cloud models<br/>any OpenAI-compatible provider"]
    R -. "optional" .-> O["Docker · Uptime Kuma · ntfy<br/>memory-core · code graph"]

Tools

119 tools in 31 groups. write tools change something; 🔒 = off until you enable it (see Security).

Every tool has its own page in capabilities/ with inputs, examples and risks.

Security

HomeShed can act on your machines, so it's built to be dull and safe out of the box:

• On your own machine (the one-line install) it talks only to the app that started it, with nothing listening on the network.
• As a Docker server, a token on every request, including from localhost, with Host and Origin checks against DNS rebinding. The one exception is /healthz, which says only {"status": "ok"} so an uptime monitor can check it. The server refuses to start without a token and a list of allowed hosts.
• Listens on 127.0.0.1 by default. Putting it on the internet is opt-in, and only behind an access proxy such as Cloudflare Access.
• Runs as an ordinary user in Docker, not root, and can't rewrite its own code there.
• Tools that act on your machines start off. Docker, git writes and code execution each need switching on. Tools that only keep notes for your AI (memory, observations, known bugs) are on.
• Per-app grants: each client gets its own token, tool list, rate limit and expiry, and only sees the tools it's granted; creating, rotating or suspending one is written to an audit log.
• SSRF guard: web.read and the network tools refuse private and metadata addresses.
• No telemetry, and requests aren't logged. Each call is recorded as tool name, time, duration and which app, never its arguments or result; usage counters keep sizes only. Memory, observations and the known-bugs list store only what your AI saves on purpose, on your machine.

Mounting the Docker socket gives root on that machine, so the compose file leaves it out until you uncomment its line (how). To report a vulnerability, see SECURITY.md.

What it's not

• Not a model provider. It includes no AI model and needs no GPU. It uses a model you run, or cloud keys you bring.
• Not a hosted service. You run it yourself, on your own machine or server.
• Not a gateway for other MCP servers. Its tools are built in. To put many existing servers behind one door, run a gateway alongside it.
• Not an autonomous agent. It acts only when your AI app calls a tool, and tools that act on your machines start switched off.

How it compares

Choose something else if you need one focused job done brilliantly (browser automation: Playwright MCP; library docs: Context7), or you already run many MCP servers and just want them behind one door (a gateway). They work alongside HomeShed.

FAQ

Roadmap

✅ available · 🟡 in progress · ⚪ planned

Want something else? Suggest it; a 👍 on an existing idea helps us choose what comes next.

HomeShed Pro

Every curated pack and fix, kept up to date.

HomeShed is free and complete, and it stays that way: every tool and all of its memory. HomeShed Pro is part of Mavis Pro, the membership from the makers of Mavis, a Windows voice assistant with 124 one-click apps. One membership covers both. It adds:

• Every curated rule pack for your AI assistant, with updates as they improve: Token Saver (cuts wasted tokens and time: bounded searches, no waiting in loops, simple work to your own model), Safe Operator (keeps keys and passwords out of commands, files and the chat, and stops risky commands with the reason), Team Sessions (several Claude sessions working together: every message checked, nothing handed over unchecked, nobody left waiting), Release Ready (keeps .env files out of git, plus Docker lockfile hygiene) and Beginner Mode (plain words, one step at a time, and a question before anything is installed or deleted).
• A curated known-bugs feed: fixes other users already found, straight into bugs.find.
• Fair terms: packs you've installed keep working if you stop paying.

Get Pro →

Connect it. On the Pro website, open your account page, then Access keys, and make a key (it starts with mav_ and is shown once). In the Control Panel, go to Settings → Account and sharing → Pro membership, choose Paste a Pro key and paste it. Without the Control Panel, run uvx homeshed-mcp pro connect and paste it there. HomeShed checks the key with the Pro website, then keeps it in its vault. Then install packs: see Rule packs.

HomeShed never asks for your Pro password; a copy that does isn't ours. Until you connect, nothing is sent to the Pro website. To stop, choose Disconnect in the same place, and revoke the key on the Pro website.

Contributing

Issues and pull requests are welcome. Start with CONTRIBUTING.md; taking part means following the Code of Conduct. If HomeShed saves you time or tokens, a ⭐ helps other people find it.

Licence

Apache-2.0. Third-party components and their licences are listed in THIRD_PARTY.md and NOTICE.