homeshed-mcp

---

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: 173 tools behind one endpoint that you run and control.

New in 0.7.0: one-click sign-in for Claude.ai and other MCP apps

Add HomeShed to your chat app in one step: paste the address, sign in, approve the 6-digit code on your Control Panel. No key to copy and paste. Every app gets its own access level, limits and an off switch, and your memory, tools and keys stay on your own machine. It's the standard MCP sign-in (OAuth 2.1 with PKCE), so any MCP app that supports sign-in can connect; tested with Claude's custom connectors. Free, in the open-source core. Set it up

Why people use it

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

New in 0.7.1

• Text to speech. Turn text into spoken MP3s with Google's Chirp 3 HD voices, made for audiobooks. It stays inside Google's free 1 million characters a month unless you allow more (guide: Control Panel > Guide > Google text to speech).
• Trusted browsers for sign-in. Approve a chat app once and tick "Trust this app on the browser that asked": its later sign-ins from that browser go straight through for 90 days. Remove any of them on the API page.
• Checked code work (Pro). In HomeShed Pro's to-do list, an item marked for checking is done only when a different session verifies the commit; a check from the builder's own model family also needs a second opinion from another family.
• A faster Control Panel. Each page loads the first time you open it, so the panel opens quicker and does less while idle.

New in 0.7.0

• One-click sign-in for Claude.ai and other MCP apps. Paste the address, sign in, approve the 6-digit code on your Control Panel: no key to copy. Every app gets only the tools you choose, its own limits and an off switch. Your HomeShed, its memory and its tools, now reach your chat apps, not just the ones on your computer. It's the standard MCP sign-in, tested with Claude's custom connectors (how). HomeShed Pro adds per-app tool sets, a savings report and approve-in-chat cards on top.
• Cheaper on every turn: the front door. Instead of loading 160+ tool descriptions, an app sees five tools that find and run all the others. Replies can be cut to just the fields you need, or kept on the server and read a page at a time, and pictures arrive as real images, not text. Fewer tokens, and small models pick the right tool more often. Switch it per app on the Control Panel's API access page.
• Choose when Claude Code compacts. One setting sets how full a chat gets before Claude Code summarises it.
• See what happened to a request. approvals.status tells your AI whether something it asked for was approved, declined or is still waiting, and who decided.

Everything else

• 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 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.

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
"Find me a tool to check SSL certificates"	tools.find lists the best matches in plain words, without loading every tool
"Was my email to the team approved yet?"	approvals.status: waiting, approved or declined, and who decided
"Read chapter one aloud as an MP3"	tts.synthesize speaks it with a Google Chirp 3 HD voice, inside the free monthly allowance, once you've set it up
"Which container keeps restarting?"	docker.container.list and docker.container.logs, once you switch Docker on

Windows: the simple way

New to all this? You only need the Claude desktop app. Claude does the installing for you, and you never need to type a command. Takes about 10 minutes.

Before you start: Claude's Code tab needs a paid Claude plan (Pro or higher). On the free plan, use Install below instead.

1. Get the Claude app. Download it from claude.com/download, install it, open it and sign in. Using the app already? Skip this step.

2. Make a folder for HomeShed. Open File Explorer, go to Documents, right-click an empty space, choose New > Folder and call it HomeShed.

3. Switch Claude to Code. In the Claude app, click the Code button, the </> icon at the top right (the Chat button beside it takes you back). This is where Claude can install things on your PC. Everything below happens in the Code view: your chats won't show there, and this one won't show under Chat. That's normal.

4. Point it at your folder. Under the message box, click the first box and pick Local. Click the box next to it, choose Open folder… and pick the HomeShed folder you made.

5. Ask Claude to install HomeShed. Copy this, paste it into the message box and press Enter:

   Install HomeShed on this Windows PC by following "For AI agents: install on Windows" in
   https://github.com/keefng8/homeshed-mcp, then start the Control Panel and give me its link.
   

   Claude asks before running each command. Read what it's going to run, then click Allow. The first download takes a minute or two. If Claude asks you to restart the app, quit it fully (right-click the Claude icon by the clock and choose Quit), open it again, open the HomeShed folder in the Code view, and say "carry on".

6. Sign in to your Control Panel. It opens in your browser at http://127.0.0.1:9090. Claude tells you where to find your first-time password. Sign in, then change the password in Settings and keep it somewhere safe.

7. Try it. Start a new session in the Code view (so Claude loads HomeShed), then ask: "What tools do you have from homeshed-mcp?"

Next time, the Control Panel starts by itself when you sign in to Windows. Bookmark http://127.0.0.1:9090.

Already use Claude Code in a terminal? You can type the same request into claude instead. To follow along in the Claude app too, type /remote-control and choose Enable Remote Control: the session then shows in the app's Code view.

You're installing HomeShed for someone who may be new to all this. Run each step in PowerShell, in the folder they opened. Say what each command does before you run it. Never print or save their keys or tokens.

1. uv, which runs HomeShed. If uvx --version fails, install it with powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex", then make it usable in this shell: $env:Path = "$env:USERPROFILE\.local\bin;$env:Path".
2. Add HomeShed to Claude Code. If the claude command works, run claude mcp add -s user homeshed-mcp -- uvx homeshed-mcp. If it doesn't (common in the Claude app's Code view), write a .mcp.json file in this folder containing {"mcpServers": {"homeshed-mcp": {"command": "uvx", "args": ["homeshed-mcp"]}}}. Then run uvx homeshed-mcp doctor and fix anything it reports. If you installed uv in step 1, the app can't find uvx until it restarts: finish step 3 first, then ask the person to quit the app fully and open it again (the app will ask them to trust this folder's .mcp.json; they should accept).
3. The Control Panel. Run uvx --from "homeshed-mcp[panel]" homeshed-mcp panel --start --at-sign-in. It sets HomeShed up the first time (its settings and token go in the data folder; never show them), starts HomeShed and the panel in the background, opens http://127.0.0.1:9090, and starts them again whenever the person signs in to Windows. On the first start it prints where the sign-in password file is: tell the person that path, not the password. panel --stop stops both; panel --not-at-sign-in removes the sign-in start.
4. Tell them to start a new session so the HomeShed tools load, and to try "What tools do you have from homeshed-mcp?" If anything fails, run uvx homeshed-mcp doctor and follow what it says.

Install

Install only from the official sources: PyPI homeshed-mcp, ghcr.io/keefng8/homeshed-mcp, github.com/keefng8/homeshed-mcp and the MCP Registry io.github.keefng8/homeshed-mcp. Look-alikes may carry malware (more).

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:

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:

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.

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": {
      "command": "uvx",
      "args": [
        "homeshed-mcp"
      ]
    }
  }
}

The same mcpServers block works in Cursor (~/.cursor/mcp.json), Windsurf (~/.codeium/windsurf/mcp_config.json) and Cline (MCP Servers → Configure).

VS Code (.vscode/mcp.json)

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

Zed (settings.json)

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

OpenCode (opencode.json)

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

Goose (~/.config/goose/config.yaml; on Windows %APPDATA%\Block\goose\config\config.yaml)

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

Codex (~/.codex/config.toml)

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

No uv yet? Install it with one command.

Pass settings as environment variables, for example with -e in claude mcp add:

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

Setting	What it does
LOCAL_AI_BASE_URL	Your OpenAI-compatible model server (Ollama, llama.cpp, LM Studio…)
LOCAL_AI_MODEL	Which model on that server to use (needed with LOCAL_AI_BASE_URL; setup prints both)
NVIDIA_API_KEY, GROQ_API_KEY, OPENROUTER_API_KEY, MISTRAL_API_KEY, GEMINI_API_KEY, OVH_AI_ENDPOINTS_TOKEN	Cloud providers you choose to use, with your own keys (all settings)
ENABLE_TOOLS	Switch on write tools, e.g. git.commit,git.push or a whole group, git.* (dev.* runs code: opt in only if you mean it)
DATA_DIR, MEMORY_DB_PATH	Where it keeps its data and memory

Keep keys out of config files. A key passed with -e is saved in plain text in that client's config. Where your client supports it, point at an environment variable instead, and never commit a config that holds a key.

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):

Put the token init printed in an environment variable named HOMESHED_TOKEN:

• Windows: setx HOMESHED_TOKEN "paste-token-here"
• macOS: echo 'export HOMESHED_TOKEN=paste-token-here' >> ~/.zshrc
• Linux: echo 'export HOMESHED_TOKEN=paste-token-here' >> ~/.bashrc

Then open a new terminal, and run:

claude mcp add -s user --transport http homeshed-mcp 'http://127.0.0.1:8765/mcp' --header 'Authorization: Bearer ${HOMESHED_TOKEN}'

Keep the single quotes: Claude Code then saves only the variable's name and reads the token when it connects, so the token never goes into its settings file. The server keeps its copy in .env (git ignores it; back it up, since init shows the token only once). To share the setup with a team, commit a .mcp.json that names the variable ("Authorization": "Bearer ${HOMESHED_TOKEN}"), never the token itself. Better still, give each app its own key: Connect Claude Code to your server. 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.

Page	What you get
Overview	Is everything working? What your AI just did, who's connected, and what your setup has saved
Models and Reasoning	Which AI answers first and why; try the logic solver and the other reasoning tools by hand
Tools	Every tool, how often it's used, and an on/off switch for each
API access	A key for each app or agent, with only the tools you grant, a rate limit and an expiry
Keys and passwords	Stored encrypted by HomeShed; your AI uses them without ever seeing them
Containers, Uptime, Savings	Your Docker containers, your Uptime Kuma checks, and the tokens kept out of your AI's context, once you use them

With Docker, in the HomeShed folder:

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

Without Docker: make a folder for it, open a terminal there and run uvx homeshed-mcp init once (skip this if you already did). Then, in that folder:

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.

Connect a chat app with sign-in (OAuth)

Chat apps can connect by signing in, so nobody copies a token. HomeShed uses the standard MCP sign-in (OAuth 2.1 with PKCE, dynamic client registration and client metadata documents), so any MCP app that supports sign-in can connect; it's tested with Claude's custom connectors. You need the server running (Docker, above), the Control Panel (to approve each sign-in), and an https address the chat app can reach it at: a service that gives your server a public web address, such as Cloudflare Tunnel, Tailscale Funnel or Caddy.

1. In .env, set MCP_PUBLIC_URL to that address and add its name to MCP_ALLOWED_HOSTS, for example:

   MCP_PUBLIC_URL=https://mcp.example.com
   MCP_ALLOWED_HOSTS=localhost:8765,127.0.0.1:8765,mcp.example.com
   

   Then run docker compose up -d again (a plain restart doesn't read .env changes). With MCP_PUBLIC_URL unset, sign-in is off.
2. In the chat app, add a custom connector with https://mcp.example.com/mcp and choose sign-in (in Claude: "Sign in now", "Use Claude's published identity" or "Register automatically").
3. A page opens with a 6-digit code. On the Control Panel, press Waiting for you at the top of the page. Check the Sign-in waiting card shows the same code, give the app a name, choose Read-only (recommended), and press Approve.

To skip step 3 next time, tick Trust this app on the browser that asked before you approve. The same app, signing in again from that browser to the same return address, is then approved without waiting, for 90 days (up to 50 trusted browsers; not while the app is suspended). The API page lists them, each with Remove. Trust belongs to that one browser, never to the app's name, because anyone can start a sign-in as a public app.

Each sign-in is then an app on the API page: its grants, tool view, limits, suspend and delete work as for any app, and deleting it (or rotating its key) ends its sign-in. Access tokens last an hour and refresh for 60 days; only their SHA-256 hashes are stored. A chat app left unused for 60 days signs in again. A sign-in waits 10 minutes for you, then expires. Approve only a sign-in you just started yourself, with the same code on both screens: anyone who can reach the address can start one and call themselves "Claude".

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"]

Area	Works out of the box	Connects to what you already run
Reasoning	Logic and constraint solving (Z3), task routing, complexity scoring	Break down, delegate and run tasks on your model
AI		Ask your model, or cloud models with keys you bring; text to speech with Google's Chirp 3 HD voices
Memory	Facts by category, relevance-ranked recall, a memory per project	A self-hosted memory-core instead of the built-in store
Code & git	Status, diff; commit, push, pull, clone, branch (off until you enable them); find dead Python files; catch webhooks that lose retries; six silent Strapi bugs	Build, lint and test runners (off, opt-in)
Machines	System info and health, DNS lookup, port checks, file listings	Docker containers, Uptime Kuma, ntfy notifications; check your own public sites for exposed admin pages, /.env and /.git
Knowledge	A known-bugs list: "has this error been seen before?"; find API keys left in your Claude Code history, and where to rotate them	Code-graph questions (graphify)
Publishing	Is a repo ready for GitHub (with a fix per gap); do the docs match the code; private details and secrets before you publish; release progress an agent reports
Glue	Chain tools into one workflow; find the right tool from plain English

Tools

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

Tool	What it does	Risk	Needs
agents.inbox	Your own messages from other agents, newest first (unread by default; reading marks them read). The owner may inspect one agent's mailbox, read-only.	write	nothing
agents.list	The other AI apps connected to this tool server that you can message (and the owner): id, label, last seen, and your unread messages from each.	read	nothing
agents.roster	Who's who among the agents: each one's name, role and how to reach it (SendMessage, cloud or mailbox), owner-confirmed rows first.	read	nothing
agents.roster_set	Add yourself or another agent (a cloud session, a mailbox-only app) to the roster with its role; the owner confirms it in the Control Panel.	write	nothing
agents.send	Leave another connected AI app a short message (1-2000 characters) it reads with agents.inbox; to="owner" goes to the owner's inbox instead.	write	nothing

Tool	What it does	Risk	Needs
apis.find	Find APIs in the shared catalog by need, e.g. 'text to speech' or 'free web search'.	read	nothing
apis.list	List APIs in the shared catalog (what APIs exist, cost, local vs cloud, status, how to use), filtered by category/cost/local/status. Never contains secrets.	read	nothing

Tool	What it does	Risk	Needs
approvals.status	What happened to one request that waited for the owner (a shared-memory write, a Proxmox change, a shop request or a message to the owner): waiting, approved, declined, expired, withdrawn or parked, and who decided. An app sees only its own.	read	nothing

Tool	What it does	Risk	Needs
backup.export	Save HomeShed's settings and state (schedules, watches, app access, to-do list, approvals, observations) to one zip; vault key values never included, only their names. Owner only.	write	nothing
backup.restore	Put a backup's state back: a dry run lists what changes and gives a confirm code; the restore makes a safety backup first. Owner only.	write	nothing

Tool	What it does	Risk	Needs
bugs.export	Export the public known bugs as a shareable feed, cleaned of secrets, private addresses and user folders.	read	nothing
bugs.find	Has this error been seen before? Paste it and get the known cause and fix.	read	nothing
bugs.list	List known bugs, newest first, by status or component.	read	nothing
bugs.report	Record a known bug (or a new occurrence of one) with its cause and fix, so nobody hits it twice.	write	nothing
bugs.seen	A tool call failed: count it, and suggest it as a bug for the owner once it comes back in another session. Sent by the failure hook.	write	nothing
bugs.sync	Fetch the HomeShed Pro known-bugs feed with this install's Pro key and merge it in, so bugs.find knows every fix Pro members get.	write	a Pro key (Settings > Pro membership)

Tool	What it does	Risk	Needs
code.dead_scan	Walk a Python project's import graph from its real entry points: files nothing reaches, and init.py re-exports nothing uses (delete-with-care).	read	nothing
code.webhook_retry_check	Find webhook handlers whose catch block swallows the error and answers 200, so the sender (PayPal, Stripe) never retries.	read	nothing

Tool	What it does	Risk	Needs
commerce.requests.approve_housekeeping	A bot the owner named (Settings > Shops and social > "Bots that may approve listing housekeeping") approves one waiting Etsy details card that only changes delivery profile, shop section, production partners, materials, category, attributes or photo alt text. Prices, words, photo adds, removals or moves, publishing and Pinterest still wait for the owner. Logged as the bot's.	write	nothing
commerce.requests.list	An app's own shop requests (Printify publishes, live-product updates, Etsy listing edits): what still waits for the owner, and the owner's decisions of the last 7 days by default, up to 30 (approved, declined, expired), with notes. Check this instead of assuming something still waits.	read	nothing

Tool	What it does	Risk	Needs
dev.build	Run a build command on the machine HomeShed runs on (your computer, or its container). Real code execution, no confirmation step. The toolchain must be installed there.	write 🔒	nothing
dev.lint	Run a lint or code-quality command on the machine HomeShed runs on (your computer, or its container). Real code execution, no confirmation step. The linter must be installed there.	write 🔒	nothing
dev.node	Run a Node.js command on the machine HomeShed runs on (your computer, or its container). Real code execution, no confirmation step. Node must be installed there; the Docker image doesn't include it.	write 🔒	node on PATH
dev.python	Run a Python command on the machine HomeShed runs on (your computer, or its container). Real code execution, no confirmation step.	write 🔒	nothing
dev.test	Run a test-suite command on the machine HomeShed runs on (your computer, or its container). Real code execution, no confirmation step. The test runner must be installed there.	write 🔒	nothing

Tool	What it does	Risk	Needs
docker.container.inspect	Inspect a container's config, networking and mounts. Env values withheld by default.	read	Docker socket
docker.container.list	List containers on the target Docker host, running or all.	read	Docker socket
docker.container.logs	Fetch recent log lines from a container.	read	Docker socket
docker.container.restart	Restart a container. dry_run defaults true and IS the confirmation step.	write 🔒	Docker socket
docker.container.start	Start a stopped container. dry_run defaults true and IS the confirmation step.	write 🔒	Docker socket
docker.container.stop	Stop a container. dry_run defaults true and IS the confirmation step.	write 🔒	Docker socket
docker.network.list	List Docker networks on this host, including which containers are attached to each.	read	Docker socket
docker.volume.list	List Docker volumes on this host: name, driver, mountpoint, creation time.	read	Docker socket

Tool	What it does	Risk	Needs
docs.read	The text of a PDF, Word (.docx), Excel (.xlsx) or CSV file on this server, locally and free; long documents read on with offset; scanned PDFs say they have no text layer.	read	pypdf, openpyxl, defusedxml

Tool	What it does	Risk	Needs
email.send	Send an email from the owner's own address (SMTP) after he approves it in the Control Panel's Messages; nothing goes out without him. Plain text, up to 10 recipients.	write	an SMTP mail account (Settings > Email, SMTP_PASSWORD)
email.status	Your emails and where each is: waiting for the owner, sent, cancelled, expired or failed.	read	an SMTP mail account (Settings > Email, SMTP_PASSWORD)

Tool	What it does	Risk	Needs
etsy.ledger	What Etsy actually charged and paid the shop (listing, renewal, transaction and processing fees, sales, deposits), in pounds, paged, with a per-type sum. Read-only.	read	the owner's commerce_etsy_enabled switch, Etsy app and shop credentials (ETSY_KEYSTRING, ETSY_SHARED_SECRET, ETSY_REFRESH_TOKEN, ETSY_SHOP_ID)
etsy.listing.deactivate	Take one of the shop's active Etsy listings off sale at once (a brake for a listing that fails a check). No approval step: its own switch, a daily cap, audited, and the owner gets a push with the reason. Etsy's Shop Manager re-activates it.	write	the owner's commerce_etsy_enabled and commerce_etsy_deactivate_enabled switches, an Etsy connection made with listing edits (listings_w)
etsy.listing.get	One Etsy listing in detail: title, description, price, tags, materials, views, favourites. Read-only.	read	the owner's commerce_etsy_enabled switch, Etsy app and shop credentials (ETSY_KEYSTRING, ETSY_SHARED_SECRET, ETSY_REFRESH_TOKEN, ETSY_SHOP_ID)
etsy.listing.update	Ask to set an Etsy listing's category, materials, production partners, delivery profile, attributes (colour, occasion, recipient, holiday), extra photos (up to 5 at a time, shown to the owner as thumbnails) and the order of its photos. Nothing changes until the owner approves it; only what differs is sent; details (not photos) are re-queued after a Printify re-publish.	write	the owner's commerce_etsy_enabled and commerce_etsy_write_enabled switches, an Etsy connection made with listing edits (listings_w), the owner's approval of each change
etsy.listings.list	The Etsy shop's listings, compact and paged: id, title, state, price, quantity. Read-only.	read	the owner's commerce_etsy_enabled switch, Etsy app and shop credentials (ETSY_KEYSTRING, ETSY_SHARED_SECRET, ETSY_REFRESH_TOKEN, ETSY_SHOP_ID)
etsy.order.get	One Etsy order: status, money, items and shipments; no buyer personal details. Read-only.	read	the owner's commerce_etsy_enabled switch, Etsy app and shop credentials (ETSY_KEYSTRING, ETSY_SHARED_SECRET, ETSY_REFRESH_TOKEN, ETSY_SHOP_ID)
etsy.orders.list	The Etsy shop's orders (receipts), compact and paged; no buyer names, emails or addresses. Read-only.	read	the owner's commerce_etsy_enabled switch, Etsy app and shop credentials (ETSY_KEYSTRING, ETSY_SHARED_SECRET, ETSY_REFRESH_TOKEN, ETSY_SHOP_ID)

Tool	What it does	Risk	Needs
files.list	List a directory's entries, ls -F style by default ("docs/", "notes.txt (1.2 KB)"); detail=full gives type, size, modified time and permissions. At most 100 unless limit says otherwise, with total and more telling what was left out. Metadata only, never file content.	read	nothing

Tool	What it does	Risk	Needs
git.branch	Create and/or switch to a git branch. Fully autonomous, no confirmation step.	write 🔒	nothing
git.clone	Clone a git repository. Fully autonomous, no confirmation step.	write 🔒	nothing
git.commit	Stage and create a git commit. Fully autonomous, no confirmation step.	write 🔒	nothing
git.diff	Unified diff for working-tree or staged changes in a git repository.	read	nothing
git.pull	Pull changes into the current branch. Fully autonomous, no confirmation step.	write 🔒	nothing
git.push	Push the current branch to a remote. Fully autonomous, no confirmation step.	write 🔒	nothing
git.status	Branch, ahead/behind tracking, and staged/unstaged/untracked files for a git repository.	read	nothing

Tool	What it does	Risk	Needs
graphify.query	Ask an already-generated graphify code graph a question via BFS/DFS traversal. Locator, not an answerer — returns src= paths to read, not final answers.	read	graphify, and a graph built for the project

Tool	What it does	Risk	Needs
image.cancel	Stop one of your image jobs: a waiting one leaves the line, a running local one is stopped. An app can cancel only jobs it started; the owner any. A paid provider's job can't be stopped once sent.	write	the local image service
image.carousel	Designs as 1080x1350 (4:5) or 1080x1920 (9:16) social slides, or a 2000x2000 (1:1) Etsy listing photo, on their own background, saved in the images promo folder for threads.publish.	write	the local image service
image.compare	Is a scene's print exactly the reference's (the mockup it was made from, or the print file), and does the tee stand out from the background? Finds the print, scores structure and colour, looks for added text, and flags a tee that blends into its background. Free, local CPU.	read	the local image service
image.delete	Delete one image the tool server keeps (an image.store upload or a paid provider's image) straight away. An app deletes only its own; the owner token may delete any.	write	nothing
image.describe	Short, plainly visible details of a design's artwork (e.g. "long gold ears"), never a breed, name, fact or guess: for writing posts and listings about a design without seeing it. Claude Haiku through the llm relay.	read	llm relay: anthropic switched on (CLAUDE_WORKSPACE_API)
image.embed	An image's SigLIP 2 embedding (768 numbers, L2-normalised; google/siglip2-base-patch16-224, Apache-2.0), for a classifier trained on the owner's ratings. Free, local CPU only, never the GPU.	read	the local image service
image.fetch	Download a finished image job's full-size original (byte for byte, the provider's own format) by job_id, not the 1024 px preview image.status gives.	read	GPU image service (IMAGE_BASE_URL) for local jobs
image.generate	Start an image generation job; returns a job_id immediately. Default: free local GPU (stable-diffusion.cpp), whose default model FLUX.1-schnell is commercial-safe (Qwen-Image-2.1, only when named, is NON-COMMERCIAL). Opt-in PAID providers (openai, stability, replicate, fal, together, xai) via provider=..., IMAGE_DEFAULT_PROVIDER, or require_commercial=true, which refuses models whose outputs can't be sold.

Tool	What it does	Risk	Needs
inbox.amend	Correct your own open message to the owner (text, command or need); shown as edited.	write	nothing
inbox.replies	Your messages to the owner and his replies, newest first.	read	nothing
inbox.send	Leave the owner a message on the Control Panel (and his phone): a note, a command for him to run, or a decision he needs to make.	write	nothing
inbox.withdraw	Take back your own message to the owner; it leaves his list at once.	write	nothing

Tool	What it does	Risk	Needs
instagram.publish	Post one image, a carousel (2-10 images) or a video as a Reel, with a caption, to the owner's connected Instagram professional account. Public; off until the owner switches it on.	write	Instagram connected in Settings > Shops and social, the owner's switch: Let apps post to Instagram
instagram.status	Whether Instagram is connected and posting is on, the account, and posts in the last 24 hours.	read	nothing

Tool	What it does	Risk	Needs
llm.chat	One chat turn with a PAID language model (xAI Grok, Anthropic Claude, OpenAI or Google Gemini; xai by default), relayed so the caller never holds the key: the key stays in the owner's vault. Off until the owner switches the provider on and sets a daily cap (Settings > Language models); refused with the reason when off, keyless or capped. max_tokens up to 16,000; continue_if_cut asks once more when an answer stops at max_tokens and joins the two. effort (anthropic only: low, medium, high, xhigh, max) sets how hard Claude thinks, so thinking can't eat the whole max_tokens. Returns text (up to 64,000 characters), model, usage (tokens, cost) and a truncated flag.	write	the owner's llm_provider_enabled switch and an llm_daily_cap above 0, for the provider used, that provider's key in the vault: XAI_API_KEY, CLAUDE_WORKSPACE_API, OPENAI_API_KEY or GEMINI_API_KEY
llm.providers.list	Which paid language-model providers llm.chat relays to and whether each is usable now: the owner's switch (read-only here), key stored (yes/no only), why not, today's request and token caps and use, today's cost (all apps and per client), and model prices.	read	nothing

Tool	What it does	Risk	Needs
local_ai.ask	Ask your own model (LOCAL_AI_MODEL) a question, or a cloud model you've added a key for. Cheap local-first answers before escalating to a bigger model.	read	model server (LOCAL_AI_BASE_URL) or a cloud key
local_ai.classify_complexity	Score a request's complexity 0-100 with a fast, deterministic, offline regex heuristic. Advisory only -- never routes or executes anything.	read	nothing

Tool	What it does	Risk	Needs
mcp.install_links	One-click install buttons, one-line commands and per-app configs for any MCP server, from a package name or URL.	read	nothing

Tool	What it does	Risk	Needs
memory.capture	Write a fact/decision/preference into persistent memory (the built-in store, or a self-hosted TDAI memory-core), recallable in future sessions via memory.recall.	write	nothing
memory.recall	Read back raw conversation history previously written with memory.capture for a given session_id, from the built-in store or a self-hosted TDAI memory-core.	read	nothing
memory.recall_facts	Read back one category of the project's durable facts tier — scoped, fast, no unneeded text from other categories.	read	nothing
memory.recall_relevant	Recall messages from a session ranked by relevance to a query, not just chronological order.	read	nothing
memory.remember_fact	Write a durable, high-value fact into the dedicated facts tier of persistent memory — outranks topic-scoped memory.capture entries on recall.	write	nothing
memory.stats	How much memory has been read and written: an app's own totals by category, or every app's share for the owner.	read	nothing

Tool	What it does	Risk	Needs
network.dns.lookup	Resolve a hostname to its IP addresses (A/AAAA only).	read	nothing
network.exposure_check	What your own public sites answer on the paths attackers try first: admin panels, /.env, /.git, status pages. Read-only; public hosts only.	read	internet access
network.port_check	Test TCP connectivity to a host:port -- a real connection attempt, not a guess.	read	nothing

Tool	What it does	Risk	Needs
notify.send	Send a push notification via this deployment's self-hosted ntfy instance.	write	ntfy (NTFY_BASE_URL, NTFY_AUTH_TOKEN)

Tool	What it does	Risk	Needs
observe.list	List observations from the persistent observation log, filtered by status and rule.	read	nothing
observe.log	Record a rule violation, user correction, or improvement gap in the persistent observation log; flags repeat violations of the same rule for escalation to a mechanical guard.	write	nothing
observe.update	Change an observation's status (actioned, declined, superseded, parked, open) and append a dated resolution note.	write	nothing

Tool	What it does	Risk	Needs
pinterest.board.create	Ask to make a Pinterest board. Nothing is made until the owner approves it in the approvals bar.	write	the owner's social_pinterest_enabled switch, Pinterest connected, the owner's approval of each board
pinterest.boards.list	The connected Pinterest account's boards: id, name, privacy, pin count.	read	the owner's social_pinterest_enabled switch, Pinterest connected
pinterest.pin.create	Ask to make one Pinterest pin: image, title, description (with "AI-assisted design." and Pinterest's AI disclosure when AI helped), alt text and a link to one of the shop's own active Etsy listings. Nothing is pinned until the owner approves THIS pin in the approvals bar; no app or AUTO mode can approve one (Pinterest's rule).	write	the owner's social_pinterest_enabled switch, Pinterest connected, the owner's approval of each pin
pinterest.status	Whether Pinterest is connected and pinning is on, Trial (sandbox, only the owner sees pins) or Standard access, the account, and pins in the last 24 hours.	read	nothing

Tool	What it does	Risk	Needs
printify.blueprint.get	One Printify blueprint (blank product): title, brand, model and its description as plain text, with the fabric, fibre and weight lines a listing's material bullet needs. Read-only.	read	the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN)
printify.blueprints.list	Printify's catalogue of blank products, searchable and paged. Read-only.	read	the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)
printify.mockup.fetch	Copy one of a product's Printify mockups into the image store and return its image name, for image.carousel (watermarked slides) and threads.publish.	write	the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN)
printify.order.get	One Printify order: status, totals, items, shipments; no delivery address. Read-only.	read	the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)
printify.orders.list	The configured Printify shop's orders, compact and paged; no delivery addresses. Read-only.	read	the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)
printify.print_provider.get	One Printify print provider (maker): city, region and country (to confirm a UK maker; print_providers.list has no location, KB-0067) and the blueprints it makes. Read-only.	read	the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN)
printify.print_providers.list	The print providers that make one Printify blueprint: id, title, country. Read-only.	read	the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)
printify.product.create	Upload a print file and make an UNPUBLISHED product in the owner's Printify shop (for Printify's mockups). Off until the owner switches it on; daily cap.	write	PRINTIFY_API_TOKEN with uploads.write and products.write, PRINTIFY_SHOP_ID, the owner's switches: Printify read + create
printify.product.delete_draft

Tool	What it does	Risk	Needs
proxmox.health	The whole Proxmox cluster at a glance: quorum, each node's CPU, RAM and system disk, storage pools, VMs and containers running, and the alarms active now (as on the Control Panel's Proxmox tab). Read-only.	read	Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
proxmox.node.status	One Proxmox node's health: CPU, load, memory, swap, root disk, versions, uptime. Read-only.	read	Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
proxmox.nodes.list	List every node in the Proxmox cluster (one token covers the cluster): online or not, CPU and memory use, uptime, plus the cluster's name and quorum. Read-only.	read	Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
proxmox.storage.list	Storage pools on Proxmox and how full they are, on every node or one. Read-only.	read	Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
proxmox.tasks.list	Recent Proxmox tasks on a node (starts, stops, snapshots, backups) and how they ended; follow up an approved change here. Read-only.	read	Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
proxmox.vm.create	Create a new VM (qemu) or container (lxc) with Proxmox's own create options. dry_run defaults true; dry_run=false only queues it for the owner's approval. Never replaces a guest; no secrets in options.	write	Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
proxmox.vm.power	Start, stop, shut down or reboot a VM or container. dry_run defaults true; dry_run=false only queues it for the owner's approval (POST /proxmox/pending//approve).	write	Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
proxmox.vm.snapshot	Take a snapshot of a VM or container. dry_run defaults true; dry_run=false only queues it for the owner's approval. Never deletes or rolls back.	write	Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
proxmox.vm.status	One VM's or container's live status, found cluster-wide by vmid (node optional): running or not, lock, CPU, memory, disk, network. Read-only.

Tool	What it does	Risk	Needs
publisher.sign	Ask for a read-only library script's current version to be signed with HomeShed's publisher key; the owner reads the code and says Yes in the Control Panel.	write	nothing

Tool	What it does	Risk	Needs
reasoning.decompose_task	Break a task description into an ordered list of subtasks via the local model.	read	model server (LOCAL_AI_BASE_URL) or a cloud key
reasoning.delegate	Route a task and, if the local model is recommended, actually ask it. Claude path never fakes an answer.	read	model server (LOCAL_AI_BASE_URL) or a cloud key
reasoning.pipeline	Route, delegate, and persist a task's outcome to shared memory -- the full diagram in one call.	write	model server (LOCAL_AI_BASE_URL) or a cloud key
reasoning.route	Recommend whether a task should go to the local model or Claude, advisory only.	read	nothing
reasoning.solve	Solve a constraint-satisfaction/logic problem via Z3, expressed in standard SMT-LIB2 text.	read	nothing

Tool	What it does	Risk	Needs
registry.find	Find which capability best matches a natural-language request. Exact ID, then alias/keyword, then local-AI fallback. Never executes anything.	read	nothing
registry.version	A package's latest released version and when it went up, from PyPI, npm or GitHub releases, in a few hundred characters. Read-only, no keys.	read	nothing

Tool	What it does	Risk	Needs
repo.docs_check	Check a project's README and docs/ against its code: link anchors that point at real headings, documented settings the code actually reads, and documented CLI commands and options that exist.	read	nothing
repo.leak_scan	Find private details (your names, domains, private addresses, folder paths) and secrets (API keys, tokens, private keys, passwords in settings) in a folder about to go public: file, line and pattern name, never the matched text.	read	nothing
repo.progress	How far each project's release has got, as its agent last reported: percent of gates done, measured numbers such as readiness, what waits on the owner and since when, and the last 20 updates.	read	nothing
repo.progress_update	An agent preparing a project for release reports how far it has got (pass/fail gates with evidence, measured numbers, what waits on the owner), so the owner sees a percentage on a dashboard.	write	nothing
repo.readiness	How ready a project folder is to publish on GitHub: the files a pro-level repository has (README, licence, security policy, CI, templates...), with a concrete fix for each gap, plus checks inside a Dockerfile and compose file.	read	nothing
repo.stats	How a public GitHub repository is doing: stars, forks, watchers, open issues, release downloads, PyPI downloads, and views, clones and referrers when a GitHub token can read its traffic. Daily traffic is kept past GitHub's 14 days.	read	nothing

Tool	What it does	Risk	Needs
schedule.add	Run a read-only tool on a timetable (daily, weekly, every N hours or cron), as its maker, with a phone alert on change, always, on error or never. Write tools are refused.	write	apscheduler
schedule.list	Your schedules with next run, last run, whether it worked and the last 5 run summaries.	read	apscheduler
schedule.pause	Pause a schedule or resume it (also clears a pause after repeated failures).	write	apscheduler
schedule.remove	Delete one of your schedules; it stops at once.	write	apscheduler

Tool	What it does	Risk	Needs
secrets.transcript_scan	Find API keys, tokens and passwords saved in Claude Code's own transcripts, and say where to rotate each. Never returns a secret: kind, length and a fingerprint only.	read	nothing

Tool	What it does	Risk	Needs
spend.cap_set	Owner sessions only: set the daily dollar cap (0-5) of an app the owner opened to it, such as a coordinating app setting caps for the apps it runs. Other apps keep the owner-set cap.	write	nothing
spend.today	What each app (API client) has spent today on paid images and language-model calls, in dollars, against the daily cap the owner set for it. An app at its cap gets SPEND_CAP_REACHED on its paid calls; free and local tools keep working.	read	nothing

Tool	What it does	Risk	Needs
strapi.check	Lint a Strapi v5 project for six known silent bugs (missing pagination, v4 .attributes, bad filter paths, NODE_ENV, /api/api routes) and optionally probe its live /admin.	read	nothing

Tool	What it does	Risk	Needs
system.health	Check whether the configured dependencies (memory-core, the first local model, the app store backend, the Docker daemon) are reachable right now. Ones that aren't configured are skipped.	read	nothing
system.info	Hardware and OS information for the machine HomeShed runs on (your computer, or its container).	read	nothing
system.savings	Tokens saved today and per day for the last week, with what they'd have cost at a model's API price.	read	nothing

Tool	What it does	Risk	Needs
threads.insights	Views, likes, replies, reposts, quotes and shares for one of the owner's Threads posts, or the account's follower count with no post id.	read	Threads connected with the insights permission
threads.publish	Post text, one image, a carousel (2-10 images) or a video to the owner's connected Threads account. Public; off until the owner switches it on.	write	Threads connected in Settings > Shops and social, the owner's switch: Let apps post to Threads
threads.replies	The replies to one of the owner's Threads posts (read-only), for answering and for design ideas.	read	Threads connected with the read-replies permission
threads.status	Whether Threads is connected and posting is on, the account, and posts in the last 24 hours.	read	nothing

Tool	What it does	Risk	Needs
tools.call	Run any tool by name with the same checks as a direct call (access, approvals, spend limits). Optional fields keep only the parts of the reply you need; to_file keeps a big reply on the server to read with tools.result.	read	nothing
tools.describe	One tool in full: what it does and its inputs, exactly as the full tool list shows it. Use before tools.call.	read	nothing
tools.find	Find the tools for a job, best first, among the ones this app may use: each with one line on what it does and whether it reads or changes things. Start here, then tools.describe one and tools.call it.	read	nothing
tools.groups	What's here by group (shops, images, memory...), with counts, or the tools in one group with one line each. Only tools this app may use.	read	nothing
tools.result	Read back a reply tools.call kept with to_file, a page at a time, filtered by text or trimmed to fields. Kept 24 hours, only for the app that made it.	read	nothing

Tool	What it does	Risk	Needs
tts.fetch	An MP3 that tts.synthesize made, byte for byte as base64 (audio_b64), so the caller can save it. An app gets only its own files; files are kept 7 days.	read	nothing
tts.synthesize	Speak up to 5,000 bytes of text as an MP3 with a Google Chirp 3 HD voice, saved on the tool server for tts.fetch. Counted against Google's free 1 million characters a month; a piece that would pass the month's cap is refused with TTS_CAP_REACHED (free only unless the owner allows paid characters). provider="elevenlabs" uses the owner's ElevenLabs plan instead.	write	GOOGLE_TTS_SERVICE_ACCOUNT in the vault (a Google Cloud service account key file), ELEVENLABS_API_KEY in the vault, for provider="elevenlabs"
tts.usage	This month's text-to-speech characters against Google's free 1 million and the owner's paid allowance, characters left, the reset date (Pacific time) and each app's calls. provider="elevenlabs" uses the owner's ElevenLabs plan instead.	read	ELEVENLABS_API_KEY in the vault, for provider="elevenlabs"
tts.voices	Google's Chirp 3 HD voices for tts.synthesize: name, gender and language, optionally for one language. Asked of Google at most once a day per language. provider="elevenlabs" uses the owner's ElevenLabs plan instead.	read	GOOGLE_TTS_SERVICE_ACCOUNT in the vault (a Google Cloud service account key file), ELEVENLABS_API_KEY in the vault, for provider="elevenlabs"

Tool	What it does	Risk	Needs
uptime.status	Real Uptime Kuma monitor status, read directly from its database, read-only.	read	Uptime Kuma's database (KUMA_DB_PATH, default DATA_DIR/kuma/kuma.db)

Tool	What it does	Risk	Needs
web.read	Fetch a public webpage as Markdown via Jina Reader, zero API key required.	read	internet access; pages are fetched through Jina Reader (r.jina.ai)
web.search	Search the web through a self-hosted SearXNG: titles, links and short snippets; read pages with web.read.	read	a SearXNG search engine (SEARXNG_URL); free and self-hosted, no API key
web.watch	Get a phone alert when a web page changes (a price, back in stock, a new post): a schedule that checks it and alerts only when two checks agree.	write	web.read (Jina Reader), schedule.*
web.watch.check	Read a page and compare it with the last look: alert due only when two checks in a row agree on a big-enough change, or the trigger text appears.	read	web.read (Jina Reader), schedule.*

Tool	What it does	Risk	Needs
workflow.run	Chain existing capabilities into one multi-step task, stopping at the first failure.	write	nothing

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: behind an access proxy such as Cloudflare Access, or, for chat apps, with sign-in switched on, where /mcp still needs a token and a chat app gets one only after you approve it on the Control Panel.
• 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.

Get HomeShed only from official sources

Popular open-source tools attract look-alike packages and fake copies that carry malware. HomeShed is published only here:

Where	Official name
GitHub	github.com/keefng8/homeshed-mcp
PyPI	homeshed-mcp
Container image	ghcr.io/keefng8/homeshed-mcp
MCP Registry	io.github.keefng8/homeshed-mcp
Claude Code plugin	claude plugin marketplace add keefng8/homeshed-mcp

Anything else using the name, a similar name or this project's logo isn't us. Every GitHub release has a SHA256SUMS file, and PyPI packages are published from this repo's release workflow with provenance, so you can check what you install. To check a file you downloaded from a release, compare its hash with the line for it in SHA256SUMS:

certutil -hashfile homeshed-mcp.mcpb SHA256    # Windows
shasum -a 256 homeshed-mcp.mcpb                # macOS and Linux

If they don't match, don't open the file. We never ask for your tokens, keys or passwords, by email, message or anywhere else; your keys stay in your own HomeShed. If you find a fake copy, please tell us.

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

	Official reference servers	Gateways (Docker MCP Gateway, MetaMCP)	HomeShed
One endpoint for everything	❌ one server per job	✅	✅
Tools built in	➖ each installed separately	❌ bundles servers you add	✅ 173: 72 ready at once, 13 off until you enable them, 88 connect to what you run
Per-app keys, grants, rate limits and audit	❌	➖ varies	✅
Hands routine work to your own model	❌	❌	✅ if you run one
Write tools off until you enable them	➖	➖	✅

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

No. HomeShed doesn't include a model. Without one, the AI tools say they aren't set up and everything else works. If you run a model, or bring your own cloud keys, routine work can go there instead of your paid assistant.

Only where you point it: your model server, the cloud providers whose keys you add, and your memory store. Two tools reach outside services, and only when used: web.read sends the page's address to Jina Reader, which fetches the page, and bugs.find can search public GitHub issues if you opt in. If you connect HomeShed Pro, it also talks to the Pro website, using your Pro key: to check your membership and to fetch the packs and the known-bugs feed. Nothing phones home.

1. If you turned rule packs on: uvx homeshed-mcp packs off (it takes HomeShed's hook out of Claude Code's settings).
2. Remove it from your app: claude mcp remove homeshed-mcp -s user for Claude Code, or delete it from the MCP settings (or extensions, for Claude Desktop) of Cursor, VS Code or Claude Desktop.
3. Free the downloaded files: uv cache clean homeshed-mcp.
4. Only if you also want your saved memory, keys and settings gone: delete the data folder (where it is). For Docker, docker compose down -v deletes its volumes.

Only behind an access proxy (for example Cloudflare Access) as well as the token, or with sign-in for chat apps, where you approve each sign-in yourself. See Security.

Yes: one Python file plus a JSON manifest, and every MCP client sees it within its grants. See CONTRIBUTING.md.

Roadmap

✅ available · 🟡 in progress · ⚪ planned

	What
✅	173 tools across reasoning, memory, git, Docker, network and more
✅	The front door: five tools that find and run the rest, with trimmed replies and real images (0.7.0)
✅	Sign-in for MCP apps (tested with Claude.ai connectors), approved by you with a matching code (0.7.0)
✅	Per-app keys, tool grants and rate limits, with an audit log of every change to them
✅	Persistent memory, built in, one per project (or connect memory-core)
✅	Observations: log corrections, flag repeats
✅	setup and doctor commands
✅	An optional Control Panel: a web page for your install, added or removed any time
✅	Safe defaults everywhere: local-only listening, write tools off, keys generated for you
✅	One-line install for every major AI app: uvx, one-click buttons, a Claude Desktop extension
✅	Rule packs: checks before Claude Code runs a command or writes a file (your own, or Pro's curated packs)

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:

• Never lose your place. Before Claude Code compacts a long session, HomeShed Pro saves a note of what you were doing and puts it back straight after, so Claude carries on knowing the task. It comes with the Token Saver pack, and uvx homeshed-mcp packs compact-at 80 sets when compaction starts. Windows and Linux tested; macOS should work. The note stays on your own machine (how it works).
• Every curated rule pack, done for you. You can write your own packs, so why do Pro's? Because these are the lessons from real Claude Code sessions, already written, tested and kept up to date, and one command installs each: 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.
• Pro tools: the to-do list (todo.*) and trend signals (signal.*). Run uvx homeshed-mcp pro update after connecting (needs HomeShed 0.3.1 or newer); the package is checked against its signature before it's unpacked. Still to come: the decision tools, file summaries and knowledge search (with their companion services), and YouTube publishing.

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.