hutson/homelab-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: Homelab infrastructure documentation

Browse Source 
- 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>
This commit is contained in:
Hutson
2025-12-20 02:31:02 -05:00
commit 93821d1557
17 changed files with 3267 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
mcp-central/.env.example Normal file
View File

@@ -0,0 +1,16 @@
# MCP Central Server Environment Variables
# Copy to .env and fill in your values
# Airtable
AIRTABLE_API_KEY=patIrM3XYParyuHQL.xxxxx
# Exa
EXA_API_KEY=your_exa_api_key
# TickTick (if using)
TICKTICK_CLIENT_ID=your_client_id
TICKTICK_CLIENT_SECRET=your_client_secret
# Slack (if using)
SLACK_BOT_TOKEN=xoxb-xxxxx
SLACK_USER_TOKEN=xoxp-xxxxx

129
mcp-central/README.md Normal file
View File

@@ -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.

58
mcp-central/docker-compose.yml Normal file
View File

@@ -0,0 +1,58 @@
# Centralized MCP Server Stack
# Deploy on docker-host (10.10.10.206)
# All Claude Code clients connect via HTTP/SSE
version: "3.8"
services:
# MCP Gateway - Routes all MCP requests
mcp-gateway:
image: node:20-slim
container_name: mcp-gateway
working_dir: /app
volumes:
- ./gateway:/app
ports:
- "3100:3100"
command: node server.js
restart: unless-stopped
environment:
- PORT=3100
networks:
- mcp-network
# Airtable MCP Server
airtable-mcp:
image: node:20-slim
container_name: airtable-mcp
working_dir: /app
command: sh -c "npm install airtable-mcp-server && npx airtable-mcp-server"
environment:
- AIRTABLE_API_KEY=${AIRTABLE_API_KEY}
- MCP_TRANSPORT=sse
- MCP_PORT=3001
ports:
- "3001:3001"
restart: unless-stopped
networks:
- mcp-network
# Exa MCP Server
exa-mcp:
image: node:20-slim
container_name: exa-mcp
working_dir: /app
command: sh -c "npm install @anthropic/mcp-server-exa && npx @anthropic/mcp-server-exa"
environment:
- EXA_API_KEY=${EXA_API_KEY}
- MCP_TRANSPORT=sse
- MCP_PORT=3002
ports:
- "3002:3002"
restart: unless-stopped
networks:
- mcp-network
networks:
mcp-network:
driver: bridge