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

1. Node.js 18+ with npm
2. Google OAuth Credentials (required for authentication)
   • Client ID
   • Client Secret
3. Borg MCP Subscription ($1/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...

1. Visit the URL shown
2. Enter the device code
3. Authorize with your Google account
4. 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:

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

Available Tools

Once configured, these tools are available in Claude Code:

• subscribe: Create Stripe checkout session for $1/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

1. Check that .conflict file exists at ~/.claude/CLAUDE.md.conflict
2. Manually merge changes between local and conflict file
3. 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