Skip to main content

​
Self-Hosting

email-connector is fully open source and self-hostable. Running your own instance means your credentials and email data never leave your infrastructure.

​
Prerequisites

  • Node.js 18 or higher
  • A host with HTTPS support (Fly.io, Railway, Render, any VPS)

​
Quick Start

git clone https://github.com/zacslost/email-connector
cd email-connector
npm install
Your server will be available at http://localhost:3000.

​
Environment Variables

VariableDescriptionRequired
CREDENTIAL_ENCRYPTION_KEY32-byte hex key for AES-256-GCM credential encryptionYes
PORTHTTP port (default: 3000)No
HOSTBind address (default: 0.0.0.0)No
OAUTH_CLIENT_IDOAuth client IDFor Claude connector only
OAUTH_CLIENT_SECRETOAuth client secretFor Claude connector only
OAUTH_BASE_URLPublic base URL of your deploymentFor Claude connector only
The OAUTH_* variables are only required if you’re registering your self-hosted instance as a Claude connector. For local / Claude Code usage, only CREDENTIAL_ENCRYPTION_KEY is needed.

​
Generate an Encryption Key

openssl rand -hex 32
Store this key securely. If you lose it, stored credentials become unrecoverable. We recommend storing it in your deployment platform’s secrets manager.

​
Deploy to Fly.io

The repo includes a fly.toml for Fly.io deployments. 
fly auth login
fly launch
fly secrets set CREDENTIAL_ENCRYPTION_KEY=$(openssl rand -hex 32)
fly deploy

​
Deploy to Railway

  1. Fork the repo on GitHub
  2. Connect to Railway and select your fork
  3. Add CREDENTIAL_ENCRYPTION_KEY as an environment variable
  4. Railway auto-deploys on every push

​
Docker

docker build -t email-connector .
docker run -p 3000:3000 \
  -e CREDENTIAL_ENCRYPTION_KEY=your-32-byte-hex-key \
  email-connector

​
Health Check

Verify your deployment is running: 
curl https://your-domain.com/health
# → {"status":"ok","service":"claude-email-connector","transport":"streamable-http","version":"1.0.0"}

​
Connecting Claude to Your Instance

To use your self-hosted instance with Claude:
  1. Set the OAUTH_* environment variables on your server
  2. Ensure your deployment is accessible via HTTPS
  3. Register your instance URL as a custom MCP connector in Claude
  4. The OAuth flow works identically to the hosted version — Claude will redirect to your server’s /oauth/authorize endpoint

​
Using with Claude Code

For local development with Claude Code, you can connect directly without OAuth: 
# In your project directory
npx @anthropic/claude-code --mcp email-connector
Claude Code connects to http://localhost:3000/mcp and handles authentication locally.