# Deployment Guide
Complete guide for deploying the Obsidian MCP Server to your Hetzner VPS.
## Prerequisites
- Hetzner VPS (or any VPS/cloud server)
- Domain name pointed to your VPS
- SSH access to your server
- Obsidian vault in a Git repository (GitHub/GitLab)
## Step 1: Prepare Your Obsidian Vault
### 1.1 Create GitHub Repository
```bash
# On your local machine, in your Obsidian vault directory
cd /path/to/your/vault
git init
git add .
git commit -m "Initial commit"
# Create a private repository on GitHub, then:
git remote add origin https://github.com/yourusername/your-vault.git
git branch -M main
git push -u origin main
```
### 1.2 Generate GitHub Personal Access Token
1. Go to GitHub → Settings → Developer settings → Personal access tokens → Tokens (classic)
2. Click "Generate new token (classic)"
3. Give it a name: "Obsidian MCP Server"
4. Select scopes: `repo` (full control of private repositories)
5. Generate and **save the token** (you won't see it again!)
### 1.3 Install Obsidian Git Plugin
**On Desktop:**
1. Open Obsidian → Settings → Community Plugins
2. Search for "Obsidian Git"
3. Install and enable
4. Configure auto-pull and auto-push (e.g., every 5 minutes)
**On iPhone:**
1. Install "Working Copy" app or use Obsidian Git plugin (if available on mobile)
2. Clone your vault repository
3. Point Obsidian mobile to that folder
## Step 2: Set Up Domain & SSL
### 2.1 Purchase Domain
Recommended registrars:
- **Cloudflare**: $9-12/year, best DNS management
- **Porkbun**: $1-10/year, cheapest
- **Namecheap**: $8-15/year, good support
### 2.2 Point Domain to Hetzner VPS
1. Get your Hetzner VPS IP address
2. In your domain registrar's DNS settings:
```
Type: A Record
Name: @ (or your subdomain like "mcp")
Value: YOUR_VPS_IP_ADDRESS
TTL: 300 (5 minutes)
```
3. Wait 5-60 minutes for DNS propagation
### 2.3 Verify DNS
```bash
# On your local machine
ping yourdomain.com
# Should return your VPS IP
```
## Step 3: Deploy to Hetzner VPS
### 3.1 SSH into Your Server
```bash
ssh root@YOUR_VPS_IP
```
### 3.2 Install Dependencies
```bash
# Update system
apt update && apt upgrade -y
# Install Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sh get-docker.sh
# Install Docker Compose
apt install docker-compose -y
# Install Caddy (for auto-SSL)
apt install -y debian-keyring debian-archive-keyring apt-transport-https
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | tee /etc/apt/sources.list.d/caddy-stable.list
apt update
apt install caddy
```
### 3.3 Clone Your MCP Server Repository
```bash
cd /opt
git clone https://github.com/yourusername/obsidian-mcp-server.git
cd obsidian-mcp-server
```
### 3.4 Configure Environment Variables
```bash
# Create .env file
nano .env
```
Add the following (replace with your values):
```env
# Git Configuration
GIT_REPO_URL=https://github.com/yourusername/your-vault.git
GIT_BRANCH=main
GIT_TOKEN=ghp_your_github_token_here
# Server Configuration
PORT=3000
NODE_ENV=production
# Authentication - Generate a secure random key
API_KEY=your_secure_random_api_key_here
# Domain
BASE_URL=https://yourdomain.com
```
**Generate a secure API key:**
```bash
openssl rand -base64 32
```
### 3.5 Start the MCP Server
```bash
# Build and start
docker-compose up -d
# Check logs
docker-compose logs -f
```
You should see:
```
✅ Vault initialized successfully
✅ HTTP Server listening on port 3000
```
### 3.6 Configure Caddy for HTTPS
```bash
# Edit Caddyfile
nano /etc/caddy/Caddyfile
```
Add:
```
yourdomain.com {
reverse_proxy localhost:3000
}
```
**Restart Caddy:**
```bash
systemctl restart caddy
systemctl status caddy
```
Caddy automatically handles SSL certificates via Let's Encrypt!
### 3.7 Test Your Server
```bash
# From your VPS
curl https://yourdomain.com/health
# Should return:
# {"status":"ok","server":"obsidian-mcp-server"}
```
## Step 4: Configure Claude Code
### 4.1 Desktop Configuration
Edit: `%APPDATA%\Roaming\Claude\claude_desktop_config.json` (Windows)
Or: `~/Library/Application Support/Claude/claude_desktop_config.json` (Mac)
Add:
```json
{
"mcpServers": {
"obsidian": {
"url": "https://yourdomain.com/sse?apiKey=YOUR_API_KEY_HERE"
}
}
}
```
Restart Claude Desktop.
### 4.2 Mobile Configuration
1. Go to https://claude.ai (in browser, not app)
2. Log in to your account
3. Go to Settings → Integrations
4. Add Remote MCP Server:
- URL: `https://yourdomain.com/sse?apiKey=YOUR_API_KEY_HERE`
5. Save
Now open Claude on your iPhone - it will connect to your MCP server!
## Step 5: Test the Integration
### Desktop Test
In Claude Desktop, try:
```
Create a new note called "test.md" with the content "Hello from Claude!"
```
### Verify on GitHub
Check your GitHub repository - you should see a new commit with the note.
### Mobile Test
On your iPhone in Claude:
```
Read my test.md note
```
It should return the content you just created!
### Obsidian Test
Open Obsidian and pull changes - you should see the new note appear.
## Maintenance
### View Logs
```bash
docker-compose logs -f
```
### Restart Server
```bash
docker-compose restart
```
### Update Server
```bash
cd /opt/obsidian-mcp-server
git pull
docker-compose down
docker-compose build
docker-compose up -d
```
### Backup
Your notes are automatically backed up to GitHub! But also:
```bash
# Backup vault volume
docker run --rm -v obsidian-mcp-server_vault-data:/data -v $(pwd):/backup alpine tar czf /backup/vault-backup.tar.gz /data
```
## Troubleshooting
### Can't Connect from Mobile
1. Check DNS: `ping yourdomain.com`
2. Check SSL: Visit `https://yourdomain.com/health` in browser
3. Check API key in URL matches `.env`
4. Check Caddy logs: `journalctl -u caddy -f`
### Git Errors
1. Check token permissions on GitHub
2. Verify repository URL is correct
3. Check logs: `docker-compose logs`
### Port Already in Use
```bash
# Find what's using port 3000
lsof -i :3000
# Kill it or change PORT in .env
```
## Security Best Practices
1. **Never commit `.env` file** - it contains secrets!
2. **Use strong API keys** - generate with `openssl rand -base64 32`
3. **Keep system updated**: `apt update && apt upgrade`
4. **Enable firewall**:
```bash
ufw allow 22/tcp
ufw allow 80/tcp
ufw allow 443/tcp
ufw enable
```
5. **Monitor logs** regularly for suspicious activity
## Cost Breakdown
- Domain: ~$1-12/year
- Hetzner VPS: (you already have)
- GitHub: $0 (free private repos)
- SSL Certificate: $0 (Let's Encrypt via Caddy)
**Total new cost: ~$1-12/year**
