Name: HA-MCP
Availability: InStock
Author: onepush

Deploy and Host self hosted HA-MCP (AI/ML) on Railway

This template deploys HA-MCP, an OAuth-protected MCP server that lets Claude, ChatGPT and other AI assistants search, control and automate your Home Assistant.

About Hosting HA-MCP open-source software on Railway (self hosted HA-MCP template)

This template runs the unmodified upstream ha-mcp 9.2.0 image, the MIT-licensed homeassistant-ai/ha-mcp server, as one service with a public HTTPS domain and a volume at /home/mcpuser/.ha-mcp. It is independent community packaging and is not affiliated with or endorsed by Home Assistant or the Open Home Foundation.

Why Deploy HA-MCP, the OAuth-protected MCP server for Home Assistant on Railway

Running the upstream integration inside Home Assistant is simplest on a home network.

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying HA-MCP on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.

Railway vs Other Hosting Providers and VPS for HA-MCP self hosting

Choosing where the always-on HTTPS endpoint runs is the main decision, so here is how Railway compares.

Provider	What You Get with Railway	What You Get with the Other Provider
DigitalOcean	A managed deploy with a public HTTPS domain, a persistent volume and health checks.	A Droplet you control, but Docker, TLS, the volume and restarts are yours to manage.
AWS	One service with the volume and domain set up from the template.	Broad services and fine-grained networking, with more configuration to maintain.
Hetzner	Hosting prepared from the template, with no server to patch or secure.	Low-cost bare servers where you handle the OS, Docker, firewall and updates.

Pick the option that matches how much infrastructure you want to run yourself.

Common Use Cases for hosted HA-MCP

Remote control from Claude.ai: You add the Railway domain plus /mcp as a custom connector, paste your Home Assistant long-lived access token on the consent page, and then ask Claude to turn off lights or check door sensors from anywhere.
Building automations with AI help: An assistant can read your existing automations, suggest changes, and write new ones through the same always-on server, so you describe the behavior you want instead of hand-editing YAML.
Debugging a misbehaving automation: When a motion automation does not fire, the assistant can pull traces, history, and logs for the entities involved and point at the likely cause.
Dashboard and helper maintenance: You can ask an assistant to add a card to a dashboard, create a helper, or tidy up areas and labels across a larger home.
Sharing one server across several AI clients: Because the endpoint is standard HTTPS with OAuth, a client such as ChatGPT or Claude Code can connect the same way, with each user signing in using their own Home Assistant token.

Dependencies for HA-MCP Docker hosted on Railway

This template deploys one service that runs the HA-MCP server for your Home Assistant.

Deployment Dependencies for Managed HA-MCP Service (one service: the HA-MCP app on port 8080 with a public domain, a volume at /home/mcpuser/.ha-mcp (OAuth client registrations, HMAC secret and settings), and health check /healthz (timeout 300 seconds); restart policy Always; keep one replica because of the volume)

The HA-MCP app listens on port 8080 behind a public domain. Keep one replica, because the volume holds local state.

Implementation Details for HA-MCP (ghcr.io/onepush-dev/ha-mcp:9.2.0 is the unmodified upstream ghcr.io/homeassistant-ai/ha-mcp:9.2.0 image (app unchanged) plus railway/start.sh, which creates and chowns the volume to uid 999, requires an http or https HOMEASSISTANT_URL, then setpriv to uid 999 and starts ha-mcp-oauth. Baked ENV: MCP_PORT=8080, MCP_HOST=0.0.0.0, MCP_HEALTHZ=true. The MCP endpoint is /mcp.)

The image ghcr.io/onepush-dev/ha-mcp:9.2.0 is the unmodified upstream ghcr.io/homeassistant-ai/ha-mcp:9.2.0 image plus railway/start.sh.

How does HA-MCP compare against other tools

HA-MCP vs Running the Upstream Integration Inside Home Assistant (In-Process Integration Alternative)

Where it runs: The in-process integration runs inside your Home Assistant install, so nothing extra is hosted. This template runs the same server as a separate always-on service on Railway.
Access model: The in-process integration is configured inside Home Assistant. This template uses OAuth sign-in, so each user authorizes with their own long-lived access token.
Where the in-process option wins: It is simpler on Home Assistant OS or Supervised because there is nothing else to host.

HA-MCP vs a Local Stdio MCP Process (Local Stdio Alternative)

Connection type: A stdio process runs on the same computer as your AI client. This template exposes an HTTPS endpoint at /mcp that clients on any device can reach.
Setup effort: A local install needs Python or Docker on each machine. This template needs one deploy and a connector entry in your client.
Where local stdio wins: It keeps everything on your own machine and needs no public domain.

HA-MCP with Docker vs Railway (Self-Hosted Docker Alternative)

Operations: Under Docker you manage the host, TLS, updates and restarts. On Railway the domain, HTTPS, health check and restart behavior come from the template.
Persistent state: Both need a volume for OAuth client registrations and the HMAC secret. Keep a single replica on Railway.
Where Docker wins: On a home server or VPS you already run, Docker keeps all data on hardware you control.

HA-MCP vs Running a Standalone Server on Your Own VPS (VPS Self-Hosting Alternative)

Control: A VPS gives you full control of the host and network, and you can run the unmodified upstream image yourself.
Maintenance: A VPS needs you to handle the reverse proxy, certificates and updates. This template handles the public HTTPS domain and health check for you.
Where a VPS wins: It suits users who already operate servers and want their traffic to stay inside their own infrastructure.

How to use HA-MCP on Railway?

Enter HOMEASSISTANT_URL at deploy time. Use an internet-reachable address for your Home Assistant, such as a Nabu Casa remote URL or a Cloudflare Tunnel hostname. A LAN-only name like homeassistant.local will not work from Railway.
Once the service is up, open your Home Assistant profile, go to Security, and create a long-lived access token.
In Claude.ai, open Settings, Connectors, Add custom connector, and enter your Railway domain followed by /mcp.
On the consent page, paste the Home Assistant token and authorize. A wrong token still passes the consent page, but every tool then returns AUTH_INVALID_TOKEN, so Home Assistant stays protected by its own token.
To open the settings page, use your Railway domain, then the secret path, then /settings. The secret path is also printed in Deploy Logs.
Keep one replica, because the volume holds the OAuth state. Check health at /healthz.

How to self host HA-MCP on other VPS Services (HA-MCP self hosting guide)

Clone the Repository

Clone the upstream repository and check out the pinned release, 9.2.0.

git clone https://github.com/homeassistant-ai/ha-mcp.git
cd ha-mcp
git checkout v9.2.0

Install Dependencies

Install Docker or another OCI-compatible container runtime on your VPS.

Configure Environment Variables

Set your Home Assistant URL, a public base URL, and a persistent data directory. The Home Assistant URL must be reachable from the VPS.

export HOMEASSISTANT_URL=https://your-ha-domain
export MCP_BASE_URL=https://your-domain
mkdir -p ./data

Start the HA-MCP Application

Run the image, which starts ha-mcp-oauth, and mount the data directory so OAuth registrations and the HMAC secret survive restarts.

docker run -d --name ha-mcp -p 8080:8080 \
  -e HOMEASSISTANT_URL -e MCP_BASE_URL \
  -e MCP_PORT=8080 -e MCP_HOST=0.0.0.0 \
  -v "$(pwd)/data:/home/mcpuser/.ha-mcp" \
  ghcr.io/homeassistant-ai/ha-mcp:9.2.0 ha-mcp-oauth

Railway handles HTTPS, the public domain, the persistent volume, and restarts for you.

Pricing and License of HA-MCP (HA-MCP pricing)

HA-MCP is MIT-licensed open-source software, so you can self-host it on Railway or on your own VPS at no license cost.

HA-MCP hosted vs self hosted comparison (Pricing, features, costs, and more)

HA-MCP is free MIT software, so your only cost is infrastructure.

Monthly cost of self hosting HA-MCP on Railway

Railway bills by usage, so your monthly cost depends on the RAM, CPU, volume size and any other services you run.

System Requirements for Hosting HA-MCP on a VPS

A VPS needs enough memory and disk for the Python server and its persistent volume, plus a public HTTPS endpoint that your Home Assistant can reach.

Frequently Asked Questions (FAQs)

What do I enter at deploy time?

Enter HOMEASSISTANT_URL, the address of your own Home Assistant, which must be reachable from the internet, such as a Nabu Casa remote URL or a Cloudflare Tunnel hostname.

How do I connect Claude?

In Claude.ai, open Settings, then Connectors, then Add custom connector, and enter your Railway domain followed by /mcp.

Will a LAN URL work?

No.

Where is the settings page?

It is at your Railway domain, followed by the generated MCP_SETTINGS_SECRET_PATH, followed by /settings.

Is this affiliated with Home Assistant?

No. It is not affiliated with or endorsed by Home Assistant or the Open Home Foundation.

What should I back up?

Back up the volume mounted at /home/mcpuser/.ha-mcp.