Homeshed

keefng819stars

Every tool your AI needs, in one install: a self-hosted MCP server with memory, reasoning, git, Docker, network and release tools.

Devops

Install Run on PlugMCP

GitHub

Run on PlugMCP

1# Homeshed

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
License: Apache-2.0
Last checked: 2026-10-28

Stars: 19
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install Homeshed?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Homeshed need an API key?

No required environment variable is listed on this record.

What transport does Homeshed use?

Homeshed runs locally over stdio.

When was Homeshed last checked?

Last checked 2026-10-28. Every tool your AI needs, in one install: a self-hosted MCP server with memory, reasoning, git, Docker, network and release tools.

From the publisher

Documentation

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: 167 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, 167 tools, no account, no GPU.

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 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
"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
"Which container keeps restarting?"	`docker.container.list` and `docker.container.logs`, once you switch Docker on

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.

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.
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").
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.

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

167 tools in 42 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.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) and extra photos (up to 5 at a time, shown to the owner as thumbnails). 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)
`etsy.shipping_destinations`	Where one of the shop's delivery profiles delivers: countries or regions, prices, delivery days, and whether any is in the EU.	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.shop.get`	The configured Etsy shop: name, currency, listing and sales counts, reviews, vacation mode. Read-only, proxied (the app never holds the key).	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.shop.update`	Ask to set the Etsy shop's title, announcement, messages to buyers after a purchase and additional policies, and to add shop sections. Nothing changes until the owner reads the full new texts and approves; only what differs is sent. Etsy's API has no About section.	write	the owner's commerce_etsy_enabled and commerce_etsy_shop_write_enabled switches, an Etsy connection made with shop edits (shops_w), the owner's approval of each change

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 Qwen-Image-2.1 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.	write	GPU image service (IMAGE_BASE_URL) for local-sdcpp, a provider API key in the vault for a paid provider
`image.history`	Recent generated images with the prompt each was made with, the model, seed and size, newest first: local and paid-provider images together. Read-only, no image data.	read	GPU image service (IMAGE_BASE_URL) for local images
`image.ip_check`	Vision check before listing: a brand, a known character, a real person or unsafe content in an image; for a lifestyle hero photo, a visible child (blurred background included) or something covering the print (pass image.compare's print box). Claude Haiku via the llm relay, about $0.0005 a call. Fail closed: ok false means NOT clear.	write	the owner's llm_provider_anthropic_enabled switch and an llm_daily_cap_anthropic above 0, CLAUDE_WORKSPACE_API in the vault
`image.preview`	A print file on a plain flat tee (sand, white, navy, black or any #rrggbb), front or back, at its true size: a 1024 px JPEG so the owner rates exactly what will be printed. Free, local CPU, no person or model.	write	the local image service
`image.print_file`	Turn a design on a plain background into transparent print files at a print area's exact size (300 DPI, full colour or flat colours), light-tee and dark-tee (keyline) versions.	write	GPU image service (IMAGE_BASE_URL) for local jobs
`image.promo_card`	A branded 1080x1920 (9:16) or 1080x1350 (4:5) promo card around a real product mockup: logo, headline, benefit, real GBP price, Shop now button and link, in a bold 'drop' or premium 'editorial' template, optionally on a brand frame. Saved in the images promo folder for threads.publish.	write	the local image service, a brand kit on the image service
`image.prompts`	List, add, edit or remove the owner's saved image prompts (shared with the Control Panel).	write	GPU image service (IMAGE_BASE_URL) for local jobs
`image.providers.list`	Which image providers and models exist, whether each is switched on (owner-only switches; read-only here), configured (key stored: yes/no only), usable now (daily cap), its licence, whether outputs may be sold (commercial_use true/false/check), and cost (free local vs paid per image).	read	nothing
`image.queue`	The local image service's line: busy or not, the image being made and the ones waiting.	read	GPU image service (IMAGE_BASE_URL) for local jobs
`image.status`	Check an image generation job (local or paid provider): running/done/failed, progress, elapsed time, licence; optionally the image.	read	GPU image service (IMAGE_BASE_URL) for local jobs
`image.store`	Keep an image you already have (PNG, JPEG or WebP, base64, up to 10 MB and 4096 px a side) for 7 days and get back a name the other image tools take, such as image.generate's input_images. Re-encoded on the way in: EXIF/GPS metadata removed.	write	nothing
`image.text_check`	Does a design image carry text: words, pseudo-text or a signature-like mark? Free and local (RapidOCR on the image service, ~1-2 s). Returns ok/text_found and every candidate region with its corner and score.	read	the local image service

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 or a carousel (2-10 images) 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.get`	One Printify product in detail: its enabled variants with price and cost (paged, or filtered to chosen variant ids), tags, blueprint, provider and where it's published.	read	the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)
`printify.product.publish`	Ask to publish a Printify draft to the owner's connected Etsy shop. It waits for the owner's approval in the Control Panel; only then does it go live.	write	the owner's commerce_printify_enabled and commerce_printify_publish_enabled switches, a Printify shop connected to Etsy
`printify.product.update`	Edit an unpublished Printify draft's title, description, tags, variant prices and SKUs. Drafts only (never published, mid-publish or awaiting publish approval), never under the margin floor (20%, hoodies 15%) after Etsy's fees, audited with the old values kept.	write	the owner's commerce_printify_enabled and commerce_printify_write_enabled switches
`printify.product.update_live`	Ask to change a published Printify product's title, description, tags or prices on the owner's Etsy shop. Nothing changes until the owner approves it in the Control Panel; then Printify edits it and re-publishes only the changed parts. SKUs never change on a live product; never under the margin floor (20%, hoodies 15%); capped and audited.	write	the owner's commerce_printify_enabled and commerce_printify_live_update_enabled switches, the owner's approval of each update
`printify.products.list`	The configured Printify shop's products, compact and paged. Read-only.	read	the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)
`printify.shipping`	Delivery prices for one blueprint from one print provider: handling time, and per group of variants and countries the first and each additional item's price, in Printify's currency (never converted).	read	the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN)
`printify.shops.list`	The Printify shops the token can see: id, title, sales channel. Read-only, proxied.	read	the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)
`printify.variants.list`	One blueprint's variants from one print provider: id, colour, size and print-area sizes in pixels (cost appears only on a created draft).	read	the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)

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.	read	Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
`proxmox.vms.list`	List VMs (qemu) and containers (lxc) across the whole Proxmox cluster, with status, CPU, memory and uptime; optional node filter. Read-only.	read	Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)

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 Studio 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
`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	✅ 167: 69 ready at once, 13 off until you enable them, 85 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.

If you turned rule packs on: uvx homeshed-mcp packs off (it takes HomeShed's hook out of Claude Code's settings).
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.
Free the downloaded files: uv cache clean homeshed-mcp.
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
✅	167 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.

Homeshed

keefng819stars

Every tool your AI needs, in one install: a self-hosted MCP server with memory, reasoning, git, Docker, network and release tools.

Devops

Install Run on PlugMCP

GitHub

Run on PlugMCP

1# Homeshed

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
License: Apache-2.0
Last checked: 2026-10-28

Stars: 19
Tools: —
Uptime: —

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install Homeshed?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Homeshed need an API key?

No required environment variable is listed on this record.

What transport does Homeshed use?

Homeshed runs locally over stdio.

When was Homeshed last checked?

Last checked 2026-10-28. Every tool your AI needs, in one install: a self-hosted MCP server with memory, reasoning, git, Docker, network and release tools.

From the publisher

Documentation

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, 167 tools, no account, no GPU.

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 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
"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
"Which container keeps restarting?"	`docker.container.list` and `docker.container.logs`, once you switch Docker on

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.

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

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

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}'

Add the Control Panel (optional)

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

Connect a chat app with sign-in (OAuth)

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.
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").
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.

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

167 tools in 42 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.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) and extra photos (up to 5 at a time, shown to the owner as thumbnails). 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)
`etsy.shipping_destinations`	Where one of the shop's delivery profiles delivers: countries or regions, prices, delivery days, and whether any is in the EU.	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.shop.get`	The configured Etsy shop: name, currency, listing and sales counts, reviews, vacation mode. Read-only, proxied (the app never holds the key).	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.shop.update`	Ask to set the Etsy shop's title, announcement, messages to buyers after a purchase and additional policies, and to add shop sections. Nothing changes until the owner reads the full new texts and approves; only what differs is sent. Etsy's API has no About section.	write	the owner's commerce_etsy_enabled and commerce_etsy_shop_write_enabled switches, an Etsy connection made with shop edits (shops_w), the owner's approval of each change

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 Qwen-Image-2.1 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.	write	GPU image service (IMAGE_BASE_URL) for local-sdcpp, a provider API key in the vault for a paid provider
`image.history`	Recent generated images with the prompt each was made with, the model, seed and size, newest first: local and paid-provider images together. Read-only, no image data.	read	GPU image service (IMAGE_BASE_URL) for local images
`image.ip_check`	Vision check before listing: a brand, a known character, a real person or unsafe content in an image; for a lifestyle hero photo, a visible child (blurred background included) or something covering the print (pass image.compare's print box). Claude Haiku via the llm relay, about $0.0005 a call. Fail closed: ok false means NOT clear.	write	the owner's llm_provider_anthropic_enabled switch and an llm_daily_cap_anthropic above 0, CLAUDE_WORKSPACE_API in the vault
`image.preview`	A print file on a plain flat tee (sand, white, navy, black or any #rrggbb), front or back, at its true size: a 1024 px JPEG so the owner rates exactly what will be printed. Free, local CPU, no person or model.	write	the local image service
`image.print_file`	Turn a design on a plain background into transparent print files at a print area's exact size (300 DPI, full colour or flat colours), light-tee and dark-tee (keyline) versions.	write	GPU image service (IMAGE_BASE_URL) for local jobs
`image.promo_card`	A branded 1080x1920 (9:16) or 1080x1350 (4:5) promo card around a real product mockup: logo, headline, benefit, real GBP price, Shop now button and link, in a bold 'drop' or premium 'editorial' template, optionally on a brand frame. Saved in the images promo folder for threads.publish.	write	the local image service, a brand kit on the image service
`image.prompts`	List, add, edit or remove the owner's saved image prompts (shared with the Control Panel).	write	GPU image service (IMAGE_BASE_URL) for local jobs
`image.providers.list`	Which image providers and models exist, whether each is switched on (owner-only switches; read-only here), configured (key stored: yes/no only), usable now (daily cap), its licence, whether outputs may be sold (commercial_use true/false/check), and cost (free local vs paid per image).	read	nothing
`image.queue`	The local image service's line: busy or not, the image being made and the ones waiting.	read	GPU image service (IMAGE_BASE_URL) for local jobs
`image.status`	Check an image generation job (local or paid provider): running/done/failed, progress, elapsed time, licence; optionally the image.	read	GPU image service (IMAGE_BASE_URL) for local jobs
`image.store`	Keep an image you already have (PNG, JPEG or WebP, base64, up to 10 MB and 4096 px a side) for 7 days and get back a name the other image tools take, such as image.generate's input_images. Re-encoded on the way in: EXIF/GPS metadata removed.	write	nothing
`image.text_check`	Does a design image carry text: words, pseudo-text or a signature-like mark? Free and local (RapidOCR on the image service, ~1-2 s). Returns ok/text_found and every candidate region with its corner and score.	read	the local image service

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 or a carousel (2-10 images) 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.get`	One Printify product in detail: its enabled variants with price and cost (paged, or filtered to chosen variant ids), tags, blueprint, provider and where it's published.	read	the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)
`printify.product.publish`	Ask to publish a Printify draft to the owner's connected Etsy shop. It waits for the owner's approval in the Control Panel; only then does it go live.	write	the owner's commerce_printify_enabled and commerce_printify_publish_enabled switches, a Printify shop connected to Etsy
`printify.product.update`	Edit an unpublished Printify draft's title, description, tags, variant prices and SKUs. Drafts only (never published, mid-publish or awaiting publish approval), never under the margin floor (20%, hoodies 15%) after Etsy's fees, audited with the old values kept.	write	the owner's commerce_printify_enabled and commerce_printify_write_enabled switches
`printify.product.update_live`	Ask to change a published Printify product's title, description, tags or prices on the owner's Etsy shop. Nothing changes until the owner approves it in the Control Panel; then Printify edits it and re-publishes only the changed parts. SKUs never change on a live product; never under the margin floor (20%, hoodies 15%); capped and audited.	write	the owner's commerce_printify_enabled and commerce_printify_live_update_enabled switches, the owner's approval of each update
`printify.products.list`	The configured Printify shop's products, compact and paged. Read-only.	read	the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)
`printify.shipping`	Delivery prices for one blueprint from one print provider: handling time, and per group of variants and countries the first and each additional item's price, in Printify's currency (never converted).	read	the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN)
`printify.shops.list`	The Printify shops the token can see: id, title, sales channel. Read-only, proxied.	read	the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)
`printify.variants.list`	One blueprint's variants from one print provider: id, colour, size and print-area sizes in pixels (cost appears only on a created draft).	read	the owner's commerce_printify_enabled switch, Printify token (PRINTIFY_API_TOKEN; PRINTIFY_SHOP_ID for shop tools)

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.	read	Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)
`proxmox.vms.list`	List VMs (qemu) and containers (lxc) across the whole Proxmox cluster, with status, CPU, memory and uptime; optional node filter. Read-only.	read	Proxmox VE API token (PROXMOX_TOKEN_ID, or PROXMOX_API_TOKEN)

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 Studio 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
`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`

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

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	✅ 167: 69 ready at once, 13 off until you enable them, 85 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	➖	➖	✅

FAQ

If you turned rule packs on: uvx homeshed-mcp packs off (it takes HomeShed's hook out of Claude Code's settings).
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.
Free the downloaded files: uv cache clean homeshed-mcp.
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
✅	167 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.

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 →

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.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Homeshed?

Does Homeshed need an API key?

What transport does Homeshed use?

When was Homeshed last checked?

Documentation

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

Why people use it

Try it: things to ask

Install

One-line commands

Claude Desktop

VS Code (.vscode/mcp.json)

Zed (settings.json)

OpenCode (opencode.json)

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

Codex (~/.codex/config.toml)

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

Add the Control Panel (optional)

Connect a chat app with sign-in (OAuth)

What your AI can do

Tools

Security

Get HomeShed only from official sources

What it's not

How it compares

FAQ

Roadmap

HomeShed Pro

Contributing

Licence

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Homeshed?

Does Homeshed need an API key?

What transport does Homeshed use?

When was Homeshed last checked?

Documentation

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

Why people use it

Try it: things to ask

Install

One-line commands

Claude Desktop

VS Code (.vscode/mcp.json)

Zed (settings.json)

OpenCode (opencode.json)

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

Codex (~/.codex/config.toml)

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

Add the Control Panel (optional)

Connect a chat app with sign-in (OAuth)

What your AI can do

Tools

Security

Get HomeShed only from official sources

What it's not

How it compares

FAQ

Roadmap

HomeShed Pro

Contributing

Licence

VS Code (`.vscode/mcp.json`)

Zed (`settings.json`)

OpenCode (`opencode.json`)

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

Codex (`~/.codex/config.toml`)

VS Code (`.vscode/mcp.json`)

Zed (`settings.json`)

OpenCode (`opencode.json`)

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

Codex (`~/.codex/config.toml`)