# 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](https://kody.codes). Tools execute on this process. Kody reaches them
over HTTPS after CIMD OAuth. The official Kody guide is
[Connect a home MCP server](https://kody.codes/guides/local-mcp-tunnels).

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](docs/use-cases.md).

## Quick start

### Local development

Requires Node 24.

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

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

See [Docker](docs/docker.md) for volumes, NAS-style Container Manager notes, and
image updates.

## Docs

- [Getting started](docs/getting-started.md)
- [Use cases](docs/use-cases.md)
- [Docker](docs/docker.md)
- [Cloudflare Tunnel](docs/cloudflare-tunnel.md)
- [Cloudflare Access](docs/cloudflare-access.md)
- [OAuth and CIMD](docs/oauth-cimd.md)
- [Adding tools](docs/adding-tools.md)
- [Connecting Kody](docs/connecting-kody.md)

## Connect to Kody

1. Publish this process at an HTTPS hostname (Tunnel + Access).
2. Open [`/account/mcp-servers`](https://kody.codes/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](docs/connecting-kody.md).

## 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`](https://github.com/kody-bot).