Home MCP starter

<p align="center"> <img src="docs/images/social-preview.jpg" alt="GitHub repo kody-bot/home-mcp-starter. Home MCP starter: Kody cannot reach localhost. This server is the process that can — notes, devices, and local CLIs on your NAS." width="1280"> </p>

A small Streamable HTTP MCP server you run on a home machine or NAS and connect to Kody. Tools execute on this process. Kody reaches them over HTTPS after CIMD OAuth. The official Kody guide is Connect a home MCP server.

Household notes ship as the replace-me surface. Fork the repo, swap those tools for the LAN APIs and local CLIs you actually want, then publish the host with Cloudflare Tunnel and Access.

Use cases

• Keep a private notes file (or an Obsidian vault sidecar) on the same box
• Drive home devices that only answer on the LAN
• Wrap a local CLI your laptop already trusts
• Host automations next to a NAS share

Kody runs in the cloud. It cannot open localhost on your network. This server is the process that can, and the public MCP URL is how Kody dials in. See use cases.

Quick start

Local development

Requires Node 24.

cp .env.example .env
npm install
npm run dev

The status page is http://127.0.0.1:4040/. Health is /health. MCP is /mcp.

Docker

cp .env.example .env
# Set HOME_MCP_PUBLIC_BASE_URL to the HTTPS hostname you will publish.
docker compose up --build -d

See Docker for volumes, NAS-style Container Manager notes, and image updates.

Docs

• Getting started
• Use cases
• Docker
• Cloudflare Tunnel
• Cloudflare Access
• OAuth and CIMD
• Adding tools
• Connecting Kody

Connect to Kody

1. Publish this process at an HTTPS hostname (Tunnel + Access).
2. Open /account/mcp-servers.
3. Add the server as home with your public /mcp URL.
4. Open the authorization URL, pass Access if prompted, and approve.
5. Search capabilities under mcp:home.

Details live in Connecting Kody.

Security

• MCP clients authenticate with CIMD-only OAuth and PKCE S256. There is no Dynamic Client Registration endpoint.
• The RFC 8707 resource parameter must equal this server's MCP URL.
• Cloudflare Access protects human paths (/authorize, /). Machine paths (/mcp, /token, /revoke, /.well-known, /health) stay reachable so Kody can complete OAuth and call tools. Access is not a substitute for MCP OAuth.
• The LAN origin is trusted. Do not expose an unrestricted shell. Keep tools narrow.
• Issue one OAuth grant per Kody account. Do not share a bearer token across accounts.

Community

Kody is Kent C. Dodds' character. This is the official home MCP starter from kody-bot.