MCP Server

The Lumbox MCP server gives AI tools (Claude Desktop, Claude Code, Cursor, etc.) direct access to email capabilities — creating inboxes, waiting for OTPs, sending emails, and more.

Quick Start

1. Get your API key

2. Install (one command)

Claude Code:

claude mcp add lumbox -- npx @lumbox/mcp-server

Then set your API key:

# In your project's .mcp.json or ~/.claude/mcp.json

{
  "mcpServers": {
    "lumbox": {
      "command": "npx",
      "args": ["@lumbox/mcp-server"],
      "env": {
        "LUMBOX_API_KEY": "ak_your_key_here",
        "LUMBOX_API_URL": "https://api.lumbox.co",
        "STEEL_API_URL": "http://localhost:3000"
      }
    }
  }
}

Claude Desktop:

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "lumbox": {
      "command": "npx",
      "args": ["@lumbox/mcp-server"],
      "env": {
        "LUMBOX_API_KEY": "ak_your_key_here",
        "LUMBOX_API_URL": "https://api.lumbox.co",
        "STEEL_API_URL": "http://localhost:3000"
      }
    }
  }
}

Cursor:

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "lumbox": {
      "command": "npx",
      "args": ["@lumbox/mcp-server"],
      "env": {
        "LUMBOX_API_KEY": "ak_your_key_here",
        "LUMBOX_API_URL": "https://api.lumbox.co",
        "STEEL_API_URL": "http://localhost:3000"
      }
    }
  }
}

3. Use it

Once connected, your AI agent can:

"Create an inbox called github-bot"
"Send an email to user@example.com saying hello"
"Wait for a verification email from github.com"
"What's the OTP code in my latest email?"

Environment Variables

Variable	Default	Description
`LUMBOX_API_KEY`	(required)	Your API key (`ak_...`)
`LUMBOX_API_URL`	`https://api.lumbox.co`	API server URL
`STEEL_API_URL`	(required for browser)	Steel Browser URL (e.g. `http://localhost:3000`)
`STEEL_API_KEY`	(optional)	Steel API key if auth is enabled

Self-Hosted / Local Development

If you're running the API locally:

{
  "mcpServers": {
    "lumbox": {
      "command": "node",
      "args": ["/path/to/lumbox/apps/mcp-server/dist/index.js"],
      "env": {
        "LUMBOX_API_KEY": "ak_your_key_here",
        "LUMBOX_API_URL": "http://localhost:3001"
      }
    }
  }
}

Build first: cd apps/mcp-server && npx tsc

HTTP Mode (Hosted)

For remote AI tools that need HTTP instead of stdio:

# Development
MCP_PORT=3002 bun run dev:http

# Production
node dist/http.js

Authentication

Clients authenticate with a Bearer token on the initial request:

Authorization: Bearer ak_your_key_here

Session Flow

Initialize — POST /mcp with Bearer token + initialize request
RPC calls — POST /mcp with Mcp-Session-Id header
SSE stream — GET /mcp with Mcp-Session-Id for server-to-client messages
Terminate — DELETE /mcp with Mcp-Session-Id

Docker

docker build -t lumbox-mcp apps/mcp-server/
docker run -p 3002:3002 -e LUMBOX_API_URL=http://api:3001 lumbox-mcp

Available Tools (40+)

Inbox Management

Tool	Description
`create_inbox`	Create a new email inbox (returns email address)
`list_inboxes`	List all inboxes
`get_inbox`	Get inbox details and email count
`delete_inbox`	Delete an inbox and all its emails

Email (Core Agent Tools)

Tool	Description
`wait_for_email`	Block until a matching email arrives (with filters)
`get_otp`	Get the latest OTP/verification code
`list_emails`	List emails with filters (sender, category, date)
`read_email`	Read full email with parsed OTP, links, summary
`search_emails`	Search across all inboxes

Send / Reply / Forward

Tool	Description
`send_email`	Send an email from an inbox
`reply_to_email`	Reply with auto-threading headers
`forward_email`	Forward an email to another address

Threads

Tool	Description
`list_threads`	List conversation threads
`get_thread`	Get all emails in a thread

Domain Management

Tool	Description
`add_domain`	Add a custom domain (returns DNS records)
`verify_domain`	Check DNS and activate domain
`list_domains`	List all domains

SMTP Configuration (BYOS)

Tool	Description
`configure_smtp`	Configure outbound SMTP provider
`list_smtp_configs`	List SMTP configurations
`test_smtp_config`	Test an SMTP config

Thread Routing

Tool	Description
`assign_thread`	Assign an agent to a thread
`unassign_thread`	Remove an agent from a thread
`list_thread_agents`	List agents on a thread
`create_routing_rule`	Auto-route emails by sender/subject/category
`list_routing_rules`	List routing rules
`delete_routing_rule`	Delete a routing rule

Webhooks

Tool	Description
`create_webhook`	Register a webhook for email events
`list_webhooks`	List webhooks
`test_webhook`	Test a webhook
`delete_webhook`	Delete a webhook

Browser Automation

Tool	Description
`browser_navigate`	Navigate to URL, returns accessibility tree
`browser_snapshot`	Get current page state with element refs
`browser_click`	Click element by ref (@e1, @e2...)
`browser_type`	Type text into input by ref
`browser_select`	Select dropdown option
`browser_eval`	Run JavaScript on page
`browser_screenshot`	Take screenshot
`browser_save_state`	Save cookies + localStorage
`browser_load_state`	Restore saved session
`browser_close`	Close browser session

See Browser Automation for details.

Skills (Compound Actions)

Tool	Description
`skill_signup_with_email`	Navigate + fill email + submit + wait for OTP — all in one call
`skill_login_with_email`	Navigate + enter email + submit + wait for magic link/OTP
`skill_verify_email`	Wait for verification email + click the link

Credential Vault

Tool	Description
`store_credential`	Securely store a password/API key/TOTP secret (encrypted, never returned)
`login_with_credential`	Auto-inject credentials into login form via Steel (fields blurred, auto-submit)
`use_credential_in_browser`	Fill credential into a specific form field (for non-login fields)
`list_credentials`	List stored credentials (metadata only, never values)
`delete_credential`	Permanently delete a credential

See Credential Vault for security details.

Contact Lists & Marketing

Tool	Description
`create_contact_list`	Create a contact list for marketing
`list_contact_lists`	List contact lists
`add_contacts`	Add contacts to a list
`list_contacts`	List contacts in a list
`remove_contact`	Remove a contact
`delete_contact_list`	Delete a contact list
`send_marketing_email`	Send to all contacts in a list

AI Configuration (BYOK)

Tool	Description
`configure_ai`	Set up AI provider and API key
`get_ai_config`	View AI configuration

MCP Server

On this page