homeshed-mcp

<!-- Generated blocks (never edit by hand; CI fails if stale): INSTALL → python scripts/gen_install.py --package homeshed-mcp TOOLS → python scripts/gen_tools_table.py --> <p align="center"> <img src="docs/assets/banner.png" alt="HomeShed: every tool your AI needs, in one install" width="760"> </p> <!-- mcp-name: io.github.keefng8/homeshed-mcp --> <h3 align="center">Every tool your AI needs, in one install: memory, reasoning, git, Docker and more.</h3> <p align="center"> A self-hosted MCP server for Claude Code, Claude Desktop, Cursor, VS Code, OpenCode and any MCP client.<br> Your model first, the cloud when you choose. </p> <p align="center"> <a href="https://github.com/keefng8/homeshed-mcp/actions/workflows/ci.yml"><img alt="Tests" src="https://img.shields.io/github/actions/workflow/status/keefng8/homeshed-mcp/ci.yml?branch=main&label=tests"></a> <a href="https://pypi.org/project/homeshed-mcp/"><img alt="PyPI" src="https://img.shields.io/pypi/v/homeshed-mcp"></a> <a href="LICENSE"><img alt="Licence: Apache-2.0" src="https://img.shields.io/badge/licence-Apache--2.0-blue"></a> <img alt="Python 3.11+" src="https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white"> <a href="https://modelcontextprotocol.io"><img alt="Model Context Protocol" src="https://img.shields.io/badge/MCP-server-black"></a> </p> <p align="center"> <a href="#install">Install</a> · <a href="#try-it-things-to-ask">Try it</a> · <a href="#what-your-ai-can-do">What your AI can do</a> · <a href="#tools">All tools</a> · <a href="#security">Security</a> · <a href="#how-it-compares">Compare</a> · <a href="#roadmap">Roadmap</a> · <a href="#homeshed-pro">Pro</a> · <a href="#faq">FAQ</a> </p>

---

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: <!--count:total-->136<!--/count--> tools behind one endpoint that you run and control.

<p align="center"> <img src="docs/assets/hero.png" alt="The optional HomeShed Control Panel on a fresh install, beside the words: Your AI's tools, on one page. See what's running and what it saved you. A switch for every tool. A key for every app. On your own machine. Free and open source." width="820"> </p> <p align="center">_{The optional Control Panel on a fresh install. HomeShed itself runs without it.}</p>

Why people use it

Free and open source (Apache-2.0). One install, <!--count:total-->136<!--/count--> 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. Anyone can write their own in a few lines of JSON (how). Or skip the trial and error: HomeShed Pro's five packs are already written, tested on real sessions and kept up to date, and each one is a single install.
• 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.
• Your homelab at a glance. If you run Proxmox, the Control Panel's Proxmox tab and proxmox.health show every node, VM and container, and send you an alarm when something breaks and again when it recovers. A Terminal tab (off until you switch it on) gives you SSH to your own machines in the browser.
• Spend you can cap. Every app gets a daily dollar cap for paid models and images. At the cap its paid calls stop and everything free keeps working.
• Never lose your place (Pro). Before Claude Code compacts a long session, HomeShed Pro saves a note of what you were doing and puts it back straight after. More.

Try it: things to ask

Once HomeShed is added, just ask your AI. A few favourites:

| Ask your AI | What happens | |---|---| | "Have I ever pasted an API key into Claude Code?" | secrets.transcript_scan checks your saved sessions and lists each key's kind, where it is and where to rotate it, without ever showing the key | | "Remember that we deploy from the release branch", then next week: "where do we deploy from?" | memory.remember_fact saves it; memory.recall_relevant finds it in a later session | | "Seen this error before?" | bugs.find checks your known-bugs list (and Pro's feed, if you have it) for the cause and fix | | "Ann, Bob and Cat sit in a row. Ann isn't next to Bob, and Bob isn't on the left. Who sits where?" | reasoning.solve hands the logic to the Z3 solver, so the answer is proven, not guessed | | "Is this repo ready to go public?" | repo.readiness scores it with one fix per gap; repo.leak_scan finds private details and secrets first | | "Is my site leaking anything?" | network.exposure_check tries the paths attackers try first (admin pages, /.env, /.git) on your own public site | | "How's the Proxmox cluster?" | proxmox.health: quorum, each node's CPU, RAM and disk, what's running, and any alarm active now | | "How many stars and downloads did my project get?" | repo.stats: stars, forks, release and PyPI downloads, plus views and referrers with a GitHub token | | "What did my apps spend on AI today?" | spend.today: each app's spend against the daily cap you set | | "Which container keeps restarting?" | docker.container.list and docker.container.logs, once you switch Docker on |

Install

A real run, from setup to the first answers:

<p align="center"> <img src="docs/assets/demo.gif" alt="A real run: uvx homeshed-mcp setup adds HomeShed to Claude Code; Claude Code then checks a port and looks up github.com's address, and solves x + y = 10, x - y = 4 with the logic solver" width="720"> </p> <!-- INSTALL:START (generated by scripts/gen_install.py; do not edit by hand) -->

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:

| Windows (PowerShell) | macOS / Linux | |---|---| | powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 \| iex" | curl -LsSf https://astral.sh/uv/install.sh \| sh |

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:

<p> <a href="https://cursor.com/en/install-mcp?name=homeshed-mcp&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyJob21lc2hlZC1tY3AiXX0%3D"><img alt="Add to Cursor" src="https://cursor.com/deeplink/mcp-install-dark.svg" height="32"></a> <a href="https://insiders.vscode.dev/redirect/mcp/install?name=homeshed-mcp&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22homeshed-mcp%22%5D%7D"><img alt="Install in VS Code" src="https://img.shields.io/badge/VS_Code-Install-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white"></a> <a href="https://insiders.vscode.dev/redirect/mcp/install?name=homeshed-mcp&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22homeshed-mcp%22%5D%7D&quality=insiders"><img alt="Install in VS Code Insiders" src="https://img.shields.io/badge/VS_Code_Insiders-Install-24bfa5?style=for-the-badge&logo=visualstudiocode&logoColor=white"></a> <a href="https://github.com/keefng8/homeshed-mcp/releases/latest/download/homeshed-mcp.mcpb"><img alt="Claude Desktop extension" src="https://img.shields.io/badge/Claude_Desktop-.mcpb-D97757?style=for-the-badge&logo=claude&logoColor=white"></a> </p>

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.

Upgrading? uvx homeshed-mcp@latest doctor, then restart your app. Your data is kept. All install methods, and steps for AI agents.

<details><summary><b>Other apps and install methods</b> (Codex, Gemini CLI, Claude Desktop, Windsurf, Cline, Zed, OpenCode, Goose, pip)</summary>

One-line commands

| Client | Command | |---|---| | Codex CLI | codex mcp add homeshed-mcp -- uvx homeshed-mcp | | Gemini CLI | gemini mcp add homeshed-mcp uvx homeshed-mcp | | VS Code | code --add-mcp '{"name":"homeshed-mcp","command":"uvx","args":["homeshed-mcp"]}' | | Run it directly | uvx homeshed-mcp · pipx run homeshed-mcp · pip install homeshed-mcp && homeshed-mcp (in a virtual environment) |

Claude Desktop

Easiest: download homeshed-mcp.mcpb from the latest release and double-click it. Or add this to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "homeshed-mcp"