# 🚀 Cloudflare Workers Deployment Guide (Free Tier)
## Prerequisites Checklist
- [ ] Node.js installed (v18 or higher)
- [ ] Free Cloudflare account ([cloudflare.com](https://cloudflare.com))
- [ ] GitHub account for OAuth
- [ ] PostgreSQL database (Supabase/Neon free tier works!)
---
## Step-by-Step Deployment
### 1️⃣ Install Wrangler CLI
```powershell
# Install Wrangler globally
npm install -g wrangler
# Verify installation
wrangler --version
```
### 2️⃣ Login to Cloudflare
```powershell
wrangler login
```
This will open your browser. Authorize Wrangler to access your Cloudflare account.
---
### 3️⃣ Install Project Dependencies
```powershell
cd c:\Users\subin\Desktop\remote-mcp-server-with-auth
npm install
```
---
### 4️⃣ Set Up GitHub OAuth App
#### For LOCAL Development:
1. Go to [GitHub Developer Settings](https://github.com/settings/developers)
2. Click **"New OAuth App"**
3. Fill in:
- **Application name**: `MCP Server (Local Dev)`
- **Homepage URL**: `http://localhost:8792`
- **Authorization callback URL**: `http://localhost:8792/callback`
4. Click **"Register application"**
5. Copy **Client ID** → Save for later
6. Click **"Generate a new client secret"** → Copy secret → Save for later
#### For PRODUCTION:
1. Create **another** OAuth App (or update the existing one)
2. Fill in:
- **Application name**: `MCP Server (Production)`
- **Homepage URL**: `https://my-mcp-server.your-subdomain.workers.dev`
- **Authorization callback URL**: `https://my-mcp-server.your-subdomain.workers.dev/callback`
**Note**: Replace `my-mcp-server.your-subdomain` with your actual Cloudflare worker name
3. Copy credentials for production use
---
### 5️⃣ Configure Environment Variables (Local)
Your `.dev.vars` file should contain:
```env
# GitHub OAuth (Local)
GITHUB_CLIENT_ID=your_local_github_client_id
GITHUB_CLIENT_SECRET=your_local_github_client_secret
# Generate with: openssl rand -hex 32
COOKIE_ENCRYPTION_KEY=your_random_64_character_hex_string
# PostgreSQL Connection
DATABASE_URL=postgresql://username:password@host:5432/database_name
# Optional: Sentry monitoring
SENTRY_DSN=https://your-sentry-dsn@sentry.io/project-id
NODE_ENV=development
```
**Generate encryption key:**
```powershell
# If you have OpenSSL installed:
openssl rand -hex 32
# Otherwise, use Node.js:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
```
---
### 6️⃣ Create KV Namespace
```powershell
wrangler kv namespace create "OAUTH_KV"
```
**Output will look like:**
```json
{
"binding": "OAUTH_KV",
"id": "abc123def456ghi789jkl012mno345pqr"
}
```
**IMPORTANT**: Copy the `id` value!
---
### 7️⃣ Update wrangler.jsonc with KV ID
Open `wrangler.jsonc` and replace the KV namespace ID:
```jsonc
"kv_namespaces": [
{
"binding": "OAUTH_KV",
"id": "YOUR_KV_ID_HERE" // ← Replace this!
}
]
```
Also update the worker name if you want:
```jsonc
{
"name": "my-mcp-server", // ← Change this to your preferred name
// ...
}
```
---
### 8️⃣ Test Locally (Optional but Recommended)
```powershell
wrangler dev
```
Server runs at `http://localhost:8792`
**Test with Claude Desktop:**
1. Open Claude Desktop
2. Go to: Settings → Developer → Edit Config
3. Add:
```json
{
"mcpServers": {
"postgres-mcp": {
"command": "npx",
"args": [
"@modelcontextprotocol/server-remote",
"http://localhost:8792/mcp"
]
}
}
}
```
4. Restart Claude Desktop
5. Test queries like "What tables are in my database?"
---
### 9️⃣ Deploy to Cloudflare Workers
```powershell
wrangler deploy
```
**Output will show:**
```
Published my-mcp-server (1.23 sec)
https://my-mcp-server.your-subdomain.workers.dev
```
🎉 **Your MCP server is now live!**
---
### 🔟 Configure Production Secrets
Set each environment variable in production:
```powershell
# GitHub OAuth (use PRODUCTION credentials)
wrangler secret put GITHUB_CLIENT_ID
# Paste your production GitHub Client ID when prompted
wrangler secret put GITHUB_CLIENT_SECRET
# Paste your production GitHub Client Secret when prompted
# Cookie encryption
wrangler secret put COOKIE_ENCRYPTION_KEY
# Paste your encryption key when prompted
# Database URL
wrangler secret put DATABASE_URL
# Paste your PostgreSQL connection string when prompted
# Optional: Sentry
wrangler secret put SENTRY_DSN
# Paste your Sentry DSN when prompted
wrangler secret put NODE_ENV
# Type: production
```
**Alternative: Set via Cloudflare Dashboard**
1. Go to [Cloudflare Dashboard](https://dash.cloudflare.com)
2. Workers & Pages → Your worker → Settings → Variables
3. Add each secret there
---
### 1️⃣1️⃣ Update GitHub OAuth Callback URL
If you created a new production OAuth app:
1. Go back to your GitHub OAuth app settings
2. Update **Homepage URL**: `https://my-mcp-server.your-subdomain.workers.dev`
3. Update **Callback URL**: `https://my-mcp-server.your-subdomain.workers.dev/callback`
---
### 1️⃣2️⃣ Connect Claude Desktop to Production
Update Claude Desktop config:
```json
{
"mcpServers": {
"postgres-mcp-prod": {
"command": "npx",
"args": [
"@modelcontextprotocol/server-remote",
"https://my-mcp-server.your-subdomain.workers.dev/mcp"
]
}
}
}
```
Restart Claude Desktop and test!
---
## 🎯 Quick Command Reference
```powershell
# Local development
wrangler dev
# Deploy to production
wrangler deploy
# View logs
wrangler tail
# Add secret
wrangler secret put SECRET_NAME
# List secrets
wrangler secret list
# Delete deployment
wrangler delete
```
---
## 🛡️ Configure User Permissions
Edit `src/index.ts` (or `src/index_sentry.ts` if using Sentry):
```typescript
// Line ~10: Add GitHub usernames who can write to database
const ALLOWED_WRITE_USERS = ["your-github-username", "teammate-username"];
```
Redeploy:
```powershell
wrangler deploy
```
---
## 📊 Optional: Enable Sentry Monitoring
1. Sign up at [sentry.io](https://sentry.io) (free tier available)
2. Create a new project:
- Platform: **Cloudflare Workers**
3. Copy your **DSN**
4. Add to production:
```powershell
wrangler secret put SENTRY_DSN
# Paste DSN when prompted
```
5. Swap files:
```powershell
# Rename current index.ts
mv src/index.ts src/index_no_sentry.ts
# Rename Sentry version to index.ts
mv src/index_sentry.ts src/index.ts
```
6. Deploy:
```powershell
wrangler deploy
```
---
## 🔍 Troubleshooting
### Issue: "KV namespace not found"
**Solution**: Make sure you updated the KV ID in `wrangler.jsonc`
### Issue: "GitHub OAuth not working"
**Solution**: Check callback URLs match exactly (with/without trailing slash)
### Issue: "Database connection fails"
**Solution**:
- Verify DATABASE_URL secret is set correctly
- Make sure database allows connections from Cloudflare IPs
- For Supabase: Enable connection pooling
### Issue: "Deployment fails"
**Solution**:
```powershell
# Clear cache and rebuild
rm -rf .wrangler
rm -rf node_modules
npm install
wrangler deploy
```
---
## 📚 Useful Links
- [Cloudflare Workers Docs](https://developers.cloudflare.com/workers/)
- [MCP Protocol Docs](https://modelcontextprotocol.io/)
- [GitHub OAuth Apps](https://github.com/settings/developers)
- [Wrangler CLI Docs](https://developers.cloudflare.com/workers/wrangler/)
---
## ✅ Post-Deployment Checklist
- [ ] Worker deployed successfully
- [ ] All secrets configured in production
- [ ] GitHub OAuth app callback URLs updated
- [ ] Tested authentication flow
- [ ] Verified database connection
- [ ] Added GitHub usernames to ALLOWED_WRITE_USERS
- [ ] Connected Claude Desktop/Cursor to production URL
- [ ] Tested all three tools (listTables, queryDatabase, executeDatabase)
---
## 🎉 You're Done!
Your MCP server is now running on Cloudflare Workers free tier!
**Next Steps:**
- Share the worker URL with your team
- Add more GitHub usernames to ALLOWED_WRITE_USERS
- Monitor usage in Cloudflare Dashboard
- Consider adding more database tools in `src/tools/`
