Initial commit: Homelab infrastructure documentation

- CLAUDE.md: Main homelab assistant context and instructions - IP-ASSIGNMENTS.md: Complete IP address assignments - NETWORK.md: Network bridges, VLANs, and configuration - EMC-ENCLOSURE.md: EMC storage enclosure documentation - SYNCTHING.md: Syncthing setup and device list - SHELL-ALIASES.md: ZSH aliases for Claude Code sessions - HOMEASSISTANT.md: Home Assistant API and automations - INFRASTRUCTURE.md: Server hardware and power management - configs/: Shared shell configurations - scripts/: Utility scripts - mcp-central/: MCP server configuration 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2025-12-20 02:31:02 -05:00
commit 93821d1557
17 changed files with 3267 additions and 0 deletions
--- a/mcp-central/README.md
+++ b/mcp-central/README.md
@@ -0,0 +1,129 @@
+# Centralized MCP Servers for Homelab
+
+## Current State of MCP Remote Access
+
+**The Problem**: Most MCP servers use `stdio` transport (local process communication).
+Claude Code clients expect to spawn local processes.
+
+**The Solution**: Use `mcp-remote` to bridge local clients to remote servers.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    docker-host (10.10.10.206)                  │
+│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐             │
+│  │ airtable-mcp│  │   exa-mcp   │  │ ticktick-mcp│   ...       │
+│  │  :3001/sse  │  │  :3002/sse  │  │  :3003/sse  │             │
+│  └─────────────┘  └─────────────┘  └─────────────┘             │
+└─────────────────────────────────────────────────────────────────┘
+              ▲               ▲               ▲
+              │               │               │
+       ┌──────┴───────────────┴───────────────┴──────┐
+       │              Tailscale / LAN                │
+       └──────┬───────────────┬───────────────┬──────┘
+              │               │               │
+    ┌─────────▼─────┐ ┌───────▼───────┐ ┌─────▼─────────┐
+    │   MacBook     │ │   Mac Mini    │ │  Windows PC   │
+    │ Claude Code   │ │ Claude Code   │ │ Claude Code   │
+    │  mcp-remote   │ │  mcp-remote   │ │  mcp-remote   │
+    └───────────────┘ └───────────────┘ └───────────────┘
+```
+
+## Setup
+
+### Step 1: Deploy MCP Servers on docker-host
+
+```bash
+ssh hutson@10.10.10.206
+cd /opt/mcp-central
+docker-compose up -d
+```
+
+### Step 2: Configure Claude Code Clients
+
+Each device needs `mcp-remote` installed and configured.
+
+**Install mcp-remote:**
+```bash
+npm install -g mcp-remote
+```
+
+**Update ~/.claude/settings.json:**
+```json
+{
+  "mcpServers": {
+    "airtable": {
+      "command": "npx",
+      "args": ["mcp-remote", "http://10.10.10.206:3001/sse"]
+    },
+    "exa": {
+      "command": "npx",
+      "args": ["mcp-remote", "http://10.10.10.206:3002/sse"]
+    },
+    "ticktick": {
+      "command": "npx",
+      "args": ["mcp-remote", "http://10.10.10.206:3003/sse"]
+    }
+  }
+}
+```
+
+**For remote access via Tailscale, use Tailscale IP:**
+```json
+{
+  "mcpServers": {
+    "airtable": {
+      "command": "npx",
+      "args": ["mcp-remote", "http://100.x.x.x:3001/sse"]
+    }
+  }
+}
+```
+
+## Which Servers Can Be Centralized?
+
+| Server | Centralizable | Notes |
+|--------|--------------|-------|
+| Airtable | Yes | Just needs API key |
+| Exa | Yes | Just needs API key |
+| TickTick | Yes | OAuth token stored server-side |
+| Slack | Yes | Bot token stored server-side |
+| Ref | Yes | API key only |
+| Beeper | No | Needs local Beeper Desktop |
+| Google Sheets | Partial | OAuth flow needs user interaction |
+| Monarch Money | Partial | Credentials stored server-side |
+
+## Alternative: Shared Config File
+
+If full centralization is too complex, you can at least share the config:
+
+1. Store `settings.json` in a synced folder (e.g., Syncthing `configs/`)
+2. Symlink from each device:
+   ```bash
+   ln -s ~/Sync/configs/claude-settings.json ~/.claude/settings.json
+   ```
+
+This doesn't centralize the servers, but ensures all devices have the same config.
+
+## Traefik Integration (Optional)
+
+Add to Traefik for HTTPS access:
+
+```yaml
+# /etc/traefik/conf.d/mcp.yaml
+http:
+  routers:
+    mcp-airtable:
+      rule: "Host(`mcp-airtable.htsn.io`)"
+      service: mcp-airtable
+      tls:
+        certResolver: cloudflare
+  services:
+    mcp-airtable:
+      loadBalancer:
+        servers:
+          - url: "http://10.10.10.206:3001"
+```
+
+Then use: `http://mcp-airtable.htsn.io/sse` in your config.