borgmcp

Borg MCP Client

Local MCP client that syncs your ~/.claude/CLAUDE.md file to the Borg MCP cloud service.

Features

• Automatic Sync: Watches ~/.claude/CLAUDE.md and auto-syncs changes to cloud
• Conflict Detection: Never lose data - conflicts are detected and backed up for manual resolution
• Secure Storage: OAuth tokens stored in OS keychain (macOS Keychain, Windows Credential Manager, Linux Secret Service)
• Offline Support: Exponential backoff retry logic handles network failures gracefully
• Google OAuth: Secure authentication via Google OAuth 2.0 device code flow

Prerequisites

• Node.js 18+ with npm
• Google OAuth Credentials (required for authentication)
  • Client ID
  • Client Secret
• Borg MCP Subscription ($2/month with 7-day trial)

Installation

1. Install Dependencies

cd client
npm install

2. Build the Client

npm run build

3. Set Up Environment Variables

Create a .env file or export these variables:

export GOOGLE_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GOOGLE_CLIENT_SECRET="your-client-secret"

4. Configure Claude Code MCP Settings

Add the client to your Claude Code MCP configuration file at ~/.config/claude/mcp_config.json:

{
  "mcpServers": {
    "borg-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-claude-md-storage/client/dist/index.js"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Important: Replace /absolute/path/to/ with the actual path to your project directory.

First-Time Setup

Authentication Flow

On first run, the client will prompt you to authenticate:

🔐 Borg MCP Authentication
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📱 Please visit: https://www.google.com/device
🔑 And enter code: XXXX-XXXX

Waiting for authorization...

• Visit the URL shown
• Enter the device code
• Authorize with your Google account
• Tokens are securely stored in your OS keychain

Subscription

After authentication, create a subscription:

Tools available:
- subscribe: Create Stripe checkout session ($2/month, 7-day trial)

Use the subscribe tool in Claude Code to get a checkout URL and complete payment.

How It Works

Initial Sync

On startup, the client performs an initial sync:

• If remote has content and local is empty → pulls from cloud
• If local has content and remote is empty → pushes to cloud
• If both exist and match → no sync needed
• If both exist and differ → conflict detection

Automatic File Watching

The client watches ~/.claude/CLAUDE.md for changes:

• Debouncing: 1 second delay to batch rapid edits
• Content Hashing: Only syncs when content actually changes (ignores temp saves)
• Real-time Upload: Changes auto-sync to cloud within seconds

Conflict Resolution

If both local and remote files have been modified since last sync:

⚠️  SYNC CONFLICT DETECTED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Both local and remote CLAUDE.md have been modified.
Local file:    ~/.claude/CLAUDE.md
Remote backup: ~/.claude/CLAUDE.md.conflict

Please resolve manually by choosing one version or merging them.
Delete the .conflict file once resolved.

Resolution Steps:

• Compare ~/.claude/CLAUDE.md (local) with ~/.claude/CLAUDE.md.conflict (remote)
• Manually merge or choose one version
• Delete .conflict file when done

Available Tools

Once configured, these tools are available in Claude Code:

• subscribe: Create Stripe checkout session for $2/month (7-day free trial)
• get_claude_md: Manually fetch CLAUDE.md from cloud
• set_claude_md: Manually upload CLAUDE.md to cloud
• delete_claude_md: Delete CLAUDE.md from cloud
• subscription_status: Check your current subscription status
• export_data: Export all your data (GDPR compliance)
• sync_now: Force immediate sync with cloud

Troubleshooting

"Authentication required" Error

Your OAuth token has expired. Re-run the client and follow the authentication flow again.

# Manually trigger re-auth by clearing tokens
node dist/index.js

Sync Conflicts Not Resolving

• Check that .conflict file exists at ~/.claude/CLAUDE.md.conflict
• Manually merge changes between local and conflict file
• Delete .conflict file to clear the conflict state

File Watcher Not Detecting Changes

• Verify ~/.claude/CLAUDE.md path exists
• Check file permissions (must be readable/writable)
• Some editors use atomic writes (rename temp file) which may delay detection

Network Failures

The client automatically retries with exponential backoff:

• Retry 1: 1 second delay
• Retry 2: 2 second delay
• Retry 3: 4 second delay
• Max retries: 3

If network is down, edits are queued and will sync once connection is restored.

Security

Token Storage

OAuth tokens are stored using platform-specific secure credential managers:

• macOS: Keychain Access
• Windows: Credential Manager
• Linux: Secret Service API (libsecret)

Tokens are never written to disk in plain text.

Authentication

• Uses Google OAuth 2.0 device code flow (designed for CLI apps)
• ID tokens are automatically refreshed when expired
• Auth tokens are automatically injected into all remote API calls

Development

Running from Source

npm run dev

Building

npm run build

Testing

npm test

Architecture

┌─────────────────┐
│  Claude Code    │
└────────┬────────┘
         │ stdio MCP
         │
┌────────▼────────┐
│  Borg MCP       │◄──┐
│  Client         │   │ File Watcher
└────────┬────────┘   │ (chokidar)
         │            │
         │         ┌──▼──────────────┐
         │         │ ~/.claude/      │
         │         │ CLAUDE.md       │
         │         └─────────────────┘
         │ HTTPS + Auth
         │
┌────────▼────────┐
│ api.borgmcp.ai  │
│ (Remote Server) │
└─────────────────┘

License

MIT