Skip to content

Commit 62b9e95

Browse files
JohnBarton27JohnBarton27
committed
docs: Update docs for Linux guide
1 parent b54778c commit 62b9e95

3 files changed

Lines changed: 257 additions & 2 deletions

File tree

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -39,7 +39,7 @@
3939
*No paid subscription required.* Click on your operating system:
4040

4141
<p>
42-
<a href="https://homeassistant-ai.github.io/ha-mcp/guide-macos/"><img src="https://img.shields.io/badge/Setup_Guide_for_macOS-000000?style=for-the-badge&logo=apple&logoColor=white" alt="Setup Guide for macOS" height="120"></a>&nbsp;&nbsp;&nbsp;&nbsp;<a href="https://homeassistant-ai.github.io/ha-mcp/guide-windows/"><img src="https://img.shields.io/badge/Setup_Guide_for_Windows-0078D6?style=for-the-badge&logo=windows&logoColor=white" alt="Setup Guide for Windows" height="120"></a>
42+
<a href="https://homeassistant-ai.github.io/ha-mcp/guide-macos/"><img src="https://img.shields.io/badge/Setup_Guide_for_macOS-000000?style=for-the-badge&logo=apple&logoColor=white" alt="Setup Guide for macOS" height="120"></a>&nbsp;&nbsp;&nbsp;&nbsp;<a href="https://homeassistant-ai.github.io/ha-mcp/guide-linux/"><img src="https://img.shields.io/badge/Setup_Guide_for_Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black" alt="Setup Guide for Linux" height="120"></a>&nbsp;&nbsp;&nbsp;&nbsp;<a href="https://homeassistant-ai.github.io/ha-mcp/guide-windows/"><img src="https://img.shields.io/badge/Setup_Guide_for_Windows-0078D6?style=for-the-badge&logo=windows&logoColor=white" alt="Setup Guide for Windows" height="120"></a>
4343
</p>
4444

4545
### Quick install (~5 min)

‎site/src/pages/guide-linux.astro‎

Lines changed: 245 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,245 @@
1+
---
2+
import Layout from '../layouts/Layout.astro';
3+
import Nav from '../components/Nav.astro';
4+
import PlatformIcon from '../components/PlatformIcon.astro';
5+
6+
const base = import.meta.env.BASE_URL;
7+
8+
const withBase = (path: string) => {
9+
const cleanPath = path.startsWith('/') ? path : `/${path}`;
10+
return `${base}${cleanPath}`;
11+
};
12+
---
13+
14+
<Layout title="Linux Setup Guide - Home Assistant MCP">
15+
<Nav active="setup" />
16+
17+
<div class="container mx-auto px-4 py-8 max-w-3xl">
18+
<!-- Header -->
19+
<header class="mb-10">
20+
<div class="flex items-center gap-2 text-sm text-slate-400 mb-4">
21+
<a href={withBase('/setup')} class="hover:text-white">&larr; Back to Setup</a>
22+
</div>
23+
<div class="flex items-center gap-4 mb-4">
24+
<PlatformIcon icon="linux" size={40} class="text-[var(--text-secondary)] flex-shrink-0" />
25+
<div>
26+
<h1 class="text-3xl font-bold text-white">Linux Setup Guide</h1>
27+
<p class="text-slate-400">Claude Desktop + Home Assistant in ~10 minutes</p>
28+
</div>
29+
</div>
30+
<div class="bg-green-900/20 border border-green-700/50 rounded-xl p-4">
31+
<p class="text-green-300 font-medium">Works with free Claude account - no subscription needed.</p>
32+
</div>
33+
</header>
34+
35+
<!-- Steps -->
36+
<div class="space-y-8">
37+
<!-- Step 1 -->
38+
<section class="guide-step">
39+
<div class="step-header">
40+
<span class="step-number">1</span>
41+
<h2 class="text-xl font-semibold text-white">Create a Claude Account</h2>
42+
</div>
43+
<div class="step-content">
44+
<p class="text-slate-300 mb-4">Go to <a href="https://claude.ai" class="text-blue-400 hover:underline" target="_blank">claude.ai</a> and create a free account.</p>
45+
</div>
46+
</section>
47+
48+
<!-- Step 2 -->
49+
<section class="guide-step">
50+
<div class="step-header">
51+
<span class="step-number">2</span>
52+
<h2 class="text-xl font-semibold text-white">Run the Installer</h2>
53+
</div>
54+
<div class="step-content">
55+
<p class="text-slate-300 mb-4">Open <strong>Terminal</strong> and paste:</p>
56+
<pre class="code-block"><code>curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-linux.sh | sh</code></pre>
57+
<p class="text-slate-400 text-sm mt-3">This installs the required tools and configures Claude Desktop for the demo environment.</p>
58+
59+
<details class="mt-4">
60+
<summary class="text-slate-400 hover:text-white cursor-pointer font-medium">Manual Installation (if the installer doesn't work)</summary>
61+
<div class="mt-4 pl-4 border-l-2 border-slate-700">
62+
<h4 class="font-medium text-white mb-2">Install uv</h4>
63+
<pre class="code-block mb-4"><code>curl -LsSf https://astral.sh/uv/install.sh | sh</code></pre>
64+
65+
<h4 class="font-medium text-white mb-2">Configure Claude Desktop</h4>
66+
<ol class="text-slate-300 space-y-2 mb-4">
67+
<li>1. Open Claude Desktop</li>
68+
<li>2. <strong>Settings</strong> &rarr; <strong>Developer</strong> &rarr; <strong>Edit Config</strong></li>
69+
<li>3. Paste the following configuration:</li>
70+
</ol>
71+
<pre class="code-block"><code>{`{
72+
"mcpServers": {
73+
"Home Assistant": {
74+
"command": "uvx",
75+
"args": ["ha-mcp@latest"],
76+
"env": {
77+
"HOMEASSISTANT_URL": "https://ha-mcp-demo-server.qc-h.net",
78+
"HOMEASSISTANT_TOKEN": "demo"
79+
}
80+
}
81+
}
82+
}`}</code></pre>
83+
<p class="text-slate-400 text-sm mt-3">4. Save and restart Claude Desktop.</p>
84+
</div>
85+
</details>
86+
</div>
87+
</section>
88+
89+
<!-- Step 3 -->
90+
<section class="guide-step">
91+
<div class="step-header">
92+
<span class="step-number">3</span>
93+
<h2 class="text-xl font-semibold text-white">Install or Restart Claude Desktop</h2>
94+
</div>
95+
<div class="step-content">
96+
<p class="text-slate-300 mb-4">Download and install <strong>Claude Desktop</strong> from <a href="https://claude.ai/download" class="text-blue-400 hover:underline" target="_blank">claude.ai/download</a>.</p>
97+
<p class="text-slate-400">Already have it? Quit and reopen it to pick up the new configuration.</p>
98+
</div>
99+
</section>
100+
101+
<!-- Step 4 -->
102+
<section class="guide-step">
103+
<div class="step-header">
104+
<span class="step-number">4</span>
105+
<h2 class="text-xl font-semibold text-white">Test It</h2>
106+
</div>
107+
<div class="step-content">
108+
<p class="text-slate-300 mb-4">Open Claude Desktop and ask:</p>
109+
<pre class="code-block"><code>Can you see my Home Assistant?</code></pre>
110+
<p class="text-slate-400 text-sm mt-3">Claude should respond with a list of entities from the demo environment (lights, sensors, switches, etc.).</p>
111+
</div>
112+
</section>
113+
114+
<!-- Step 5 -->
115+
<section class="guide-step">
116+
<div class="step-header">
117+
<span class="step-number">5</span>
118+
<h2 class="text-xl font-semibold text-white">Explore the Demo</h2>
119+
</div>
120+
<div class="step-content">
121+
<p class="text-slate-300 mb-4">The demo environment is a real Home Assistant you can experiment with:</p>
122+
<div class="bg-slate-800/50 rounded-lg p-4 mb-4">
123+
<p class="text-slate-300"><strong>Web UI:</strong> <a href="https://ha-mcp-demo-server.qc-h.net" class="text-blue-400 hover:underline" target="_blank">ha-mcp-demo-server.qc-h.net</a></p>
124+
<p class="text-slate-300"><strong>Login:</strong> <code class="bg-slate-700 px-1 rounded">mcp</code> / <code class="bg-slate-700 px-1 rounded">mcp</code></p>
125+
<p class="text-slate-400 text-sm mt-2">Note: Resets weekly - your changes won't persist</p>
126+
</div>
127+
<p class="text-slate-300 mb-2">Try asking Claude:</p>
128+
<ul class="text-slate-400 space-y-1 list-disc list-inside">
129+
<li>"Turn on the kitchen lights"</li>
130+
<li>"What's the temperature in the living room?"</li>
131+
<li>"Create an automation that turns off all lights at midnight"</li>
132+
</ul>
133+
</div>
134+
</section>
135+
136+
<!-- Step 6 -->
137+
<section class="guide-step">
138+
<div class="step-header">
139+
<span class="step-number">6</span>
140+
<h2 class="text-xl font-semibold text-white">Connect Your Home Assistant</h2>
141+
</div>
142+
<div class="step-content">
143+
<p class="text-slate-300 mb-4">Ready to use your own Home Assistant? Open the config file in your text editor:</p>
144+
<pre class="code-block"><code>xdg-open "$HOME/.config/Claude/claude_desktop_config.json"</code></pre>
145+
146+
<p class="text-slate-300 mt-4 mb-4">Replace the demo values:</p>
147+
<pre class="code-block"><code>{`{
148+
"mcpServers": {
149+
"Home Assistant": {
150+
"command": "uvx",
151+
"args": ["ha-mcp@latest"],
152+
"env": {
153+
"HOMEASSISTANT_URL": "http://homeassistant.local:8123",
154+
"HOMEASSISTANT_TOKEN": "your_long_lived_token"
155+
}
156+
}
157+
}
158+
}`}</code></pre>
159+
160+
<div class="bg-amber-900/20 border border-amber-700/50 rounded-xl p-4 mt-4">
161+
<h4 class="font-medium text-amber-300 mb-2">To get your token:</h4>
162+
<ol class="text-amber-200/80 space-y-1 text-sm">
163+
<li>1. Open Home Assistant in your browser</li>
164+
<li>2. Click your username (bottom left)</li>
165+
<li>3. <strong>Security</strong> tab &rarr; <strong>Long-lived access tokens</strong></li>
166+
<li>4. Create token &rarr; Copy immediately (shown only once)</li>
167+
</ol>
168+
</div>
169+
170+
<p class="text-slate-400 mt-4">Then quit and reopen Claude Desktop.</p>
171+
</div>
172+
</section>
173+
174+
<!-- Troubleshooting -->
175+
<section class="guide-step">
176+
<div class="step-header">
177+
<span class="step-number">?</span>
178+
<h2 class="text-xl font-semibold text-white">Troubleshooting: Can't Connect to Local HA?</h2>
179+
</div>
180+
<div class="step-content">
181+
<p class="text-slate-300 mb-4">If the demo server works but your local Home Assistant doesn't, check the following:</p>
182+
183+
<div class="space-y-4">
184+
<div>
185+
<p class="text-white font-medium mb-2">1. Firewall rules</p>
186+
<p class="text-slate-300">If you run <code class="bg-slate-800 px-1 rounded">ufw</code> or <code class="bg-slate-800 px-1 rounded">firewalld</code>, make sure outbound connections to your Home Assistant IP and port are allowed. Claude Desktop spawns a subprocess that needs network access.</p>
187+
</div>
188+
189+
<div>
190+
<p class="text-white font-medium mb-2">2. http:// vs https://</p>
191+
<p class="text-slate-300">HA in container mode (Docker, K3s) uses HTTP by default. Use <code class="bg-slate-800 px-1 rounded">http://</code> unless you configured SSL/TLS or a reverse proxy.</p>
192+
</div>
193+
194+
<div>
195+
<p class="text-white font-medium mb-2">3. Python 3.13 required</p>
196+
<p class="text-slate-300 mb-2">ha-mcp requires Python 3.13+. Older versions get outdated ha-mcp with known bugs.</p>
197+
<pre class="code-block"><code>uv python install 3.13
198+
uvx --refresh ha-mcp@latest</code></pre>
199+
<p class="text-slate-400 text-sm mt-2">If uvx still picks the old Python, add <code class="bg-slate-800 px-1 rounded">"--python", "3.13"</code> to your config args.</p>
200+
</div>
201+
</div>
202+
203+
<p class="text-slate-400 text-sm mt-4">See the <a href={withBase('/faq')} class="text-blue-400 hover:underline">FAQ & Troubleshooting Guide</a> for more.</p>
204+
</div>
205+
</section>
206+
207+
<!-- Step 7 -->
208+
<section class="guide-step">
209+
<div class="step-header">
210+
<span class="step-number">7</span>
211+
<h2 class="text-xl font-semibold text-white">Share Your Feedback</h2>
212+
</div>
213+
<div class="step-content">
214+
<p class="text-slate-300 mb-4">We'd love to hear how you're using ha-mcp!</p>
215+
<ul class="space-y-2">
216+
<li><a href="https://github.com/homeassistant-ai/ha-mcp/discussions" class="text-blue-400 hover:underline" target="_blank">GitHub Discussions</a> — Share your automations, ask questions</li>
217+
<li><a href="https://github.com/homeassistant-ai/ha-mcp/issues" class="text-blue-400 hover:underline" target="_blank">GitHub Issues</a> — Report bugs or request features</li>
218+
</ul>
219+
</div>
220+
</section>
221+
</div>
222+
223+
<!-- Footer -->
224+
<div class="mt-12 pt-8 border-t border-slate-800">
225+
<p class="text-slate-400 text-center">
226+
Having issues? See the <a href={withBase('/faq')} class="text-blue-400 hover:underline">FAQ & Troubleshooting Guide</a>
227+
</p>
228+
</div>
229+
</div>
230+
</Layout>
231+
232+
<style>
233+
.guide-step {
234+
@apply bg-slate-800/30 rounded-xl border border-slate-700/50 p-6;
235+
}
236+
.step-header {
237+
@apply flex items-center gap-3 mb-4;
238+
}
239+
.step-number {
240+
@apply w-8 h-8 rounded-full bg-blue-600 text-white font-semibold flex items-center justify-center flex-shrink-0;
241+
}
242+
.step-content {
243+
@apply pl-11;
244+
}
245+
</style>

‎site/src/pages/setup.astro‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ const remoteOnlyClients = ['chatgpt', 'claude-ai'];
6666
<span class="inline-flex rounded-full h-2 w-2 bg-green-500"></span>
6767
Get Started - Easy Setup
6868
</div>
69-
<div class="grid md:grid-cols-2 gap-6 max-w-3xl mx-auto">
69+
<div class="grid md:grid-cols-3 gap-6 max-w-3xl mx-auto">
7070
<a href={withBase('/guide-macos')} class="quick-start-card group">
7171
<div class="flex items-center gap-4">
7272
<PlatformIcon icon="apple" size={40} class="text-[var(--text-secondary)]" />
@@ -77,6 +77,16 @@ const remoteOnlyClients = ['chatgpt', 'claude-ai'];
7777
</div>
7878
<span class="quick-start-badge" title="10 minutes to get you started. No subscription needed.">Quick start</span>
7979
</a>
80+
<a href={withBase('/guide-linux')} class="quick-start-card group">
81+
<div class="flex items-center gap-4">
82+
<PlatformIcon icon="linux" size={40} class="text-[var(--text-secondary)]" />
83+
<div class="text-left">
84+
<h3 class="text-lg font-semibold text-white group-hover:text-blue-400">Linux + Claude Desktop</h3>
85+
<p class="text-slate-400">Complete guided setup</p>
86+
</div>
87+
</div>
88+
<span class="quick-start-badge" title="10 minutes to get you started. No subscription needed.">Quick start</span>
89+
</a>
8090
<a href={withBase('/guide-windows')} class="quick-start-card group">
8191
<div class="flex items-center gap-4">
8292
<PlatformIcon icon="windows" size={40} class="text-[var(--text-secondary)]" />

0 commit comments

Comments
 (0)