Commune

Email for Claude Desktop, Cursor & Windsurf

[PyPI] [PyPI Downloads] [Python 3.9+] [Apache-2.0 License] [MCP] [Works with Claude] [Works with Cursor] [commune.email]

Give Claude (or any MCP client) a real email inbox and SMS. Install in 30 seconds — no cloning required.

Your AI agent can:

• Read email — list threads, search by topic, get full message history
• Send email — reply in existing threads, compose fresh messages, attach files
• Manage inboxes — create programmatic inboxes, set up custom domains, triage with tags and status
• Track delivery — get delivery stats, suppression lists, bounce and complaint events
• Send and receive SMS — provision phone numbers, send messages, search SMS history

Works with Claude Desktop, Cursor, Windsurf, or any MCP client.

Install via Smithery

[smithery badge]

Commune is published on Smithery. One-line install for any supported client:

# Install Smithery CLI (once)npm install -g @smithery/cli@latest
# Add Commune to your clientnpx @smithery/cli install commune-dev/commune --client claude      # Claude Desktopnpx @smithery/cli install commune-dev/commune --client cursor      # Cursornpx @smithery/cli install commune-dev/commune --client windsurf    # Windsurfnpx @smithery/cli install commune-dev/commune --client vscode      # VS Codenpx @smithery/cli install commune-dev/commune --client claude-code # Claude Codenpx @smithery/cli install commune-dev/commune --client cline       # Clinenpx @smithery/cli install commune-dev/commune --client roo-cline   # Roo Codenpx @smithery/cli install commune-dev/commune --client goose       # Goose

Or connect via the Smithery API for agent-to-agent use:

https://commune--commune-dev.run.tools

Example prompts

Once configured, you can give your AI assistant natural language instructions for email and SMS:

Reading email:

• "Check my support inbox for new emails"
• "Show me all unread threads in the billing inbox"
• "Find emails from customers asking about refunds this week"
• "Search for all threads about the payment issue from last month"
• "What's the full conversation history for thread conv_abc123?"
• "Show me all threads that haven't been replied to"

Sending email:

• "Reply to John's email saying we'll process his refund within 48 hours"
• "Send an email to [email protected] with subject 'Meeting tomorrow' and tell her the meeting is moved to 3pm"
• "Reply to the last message in the support thread about the broken login, staying in thread"
• "Send a follow-up to all leads from last week who didn't respond"

Organizing and triaging:

• "Tag this thread as urgent and assign it to the billing team"
• "Mark all threads older than 30 days with no reply as closed"
• "Show me the deliverability stats for the past 7 days"
• "List all suppressed email addresses in the support inbox"

SMS:

• "Provision a phone number for my agent"
• "Send an SMS to +14155551234 saying 'Your order has shipped'"
• "Show me all my SMS conversations"
• "Search my SMS messages for anything about delivery issues"

Domain and inbox management:

• "Create a new inbox called 'billing' under example.com"
• "What DNS records do I need to add to verify example.com?"
• "Show me all my verified domains"

Setup

1. Get your API key

Create an API key from your Commune dashboard. It starts with comm_.

2. Add to your MCP client

Pick your client and add the Commune server. No local files needed — uvx fetches the package automatically.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{  "mcpServers": {    "commune": {      "command": "uvx",      "args": ["commune-mcp"],      "env": {        "COMMUNE_API_KEY": "comm_your_key_here"      }    }  }}

Cursor

Open Settings → MCP → Add Server:

{  "commune": {    "command": "uvx",    "args": ["commune-mcp"],    "env": {      "COMMUNE_API_KEY": "comm_your_key_here"    }  }}

Windsurf

Open Settings → MCP, same format as Cursor.

Alternative: pip install

If you prefer pip over uvx:

pip install commune-mcp

Then use commune-mcp as the command:

{  "commune": {    "command": "commune-mcp",    "env": {      "COMMUNE_API_KEY": "comm_your_key_here"    }  }}

How It Works

Once configured, your AI agent can use Commune tools in natural conversation:

You: Check my support inbox for new emails

Agent: (calls list_domains → list_inboxes → list_threads) You have 3 new threads in [email protected]:

1. "Order not received" — 4 messages, last activity 2h ago
2. "Billing question" — 1 message, received today
3. "Feature request" — 2 messages, last activity yesterday

You: What's the order issue about?

Agent: (calls get_thread_messages) Customer [email protected] says their order #4521 shipped 5 days ago but hasn't arrived. They've followed up twice asking for tracking info.

You: Reply that we're checking with shipping and will update within 24h

Agent: (calls send_email with thread_id) Done — reply sent to [email protected] in the existing thread.

The agent decides which tools to call based on your request. You don't need to specify tool names.

How email flows through Commune MCP

Inbound (you receive email):

  User sends email       |       v  Commune receives at your inbox ([email protected])       |       v  Commune fires webhook to your app (8 retries, HMAC signed)       |       v  Your MCP client reads thread via list_threads / get_thread_messages       |       v  You ask Claude: "Reply to John saying we're on it"       |       v  Claude calls send_email with thread_id --> reply appears in John's email thread

Outbound (you send email):

  You: "Send an update email to all VIP customers"       |       v  Claude calls list_threads --> get_thread_messages --> send_email (per thread)       |       v  Commune delivers via DKIM-signed SMTP       |       v  Delivery events tracked: sent --> delivered / bounced / complained

Tools Reference

Domain Tools

These manage your email domains. Domains must be verified via DNS before you can send/receive.

list_domains

List all email domains in your account.

Parameters: None

Output:

[  {    "id": "d_abc123",    "name": "example.com",    "status": "verified",    "region": "us-east-1"  }]

create_domain

Create a new custom domain. After creating, use get_domain_records to see required DNS entries, then verify_domain to check.

Output: The created domain object with its ID and status.

get_domain_records

Get DNS records you need to add at your registrar before verification passes.

Output:

[  { "type": "MX", "name": "example.com", "value": "inbound-smtp.us-east-1.amazonaws.com", "status": "pending" },  { "type": "TXT", "name": "example.com", "value": "v=spf1 include:amazonses.com ~all", "status": "pending" }]

verify_domain

Trigger DNS verification. Call after adding records at your registrar.

Inbox Tools

Inboxes are mailboxes under a domain. support under example.com → [email protected].

list_inboxes

List inboxes. Without domain_id, lists all inboxes across all domains.

Output:

[  {    "id": "i_xyz789",    "localPart": "support",    "address": "[email protected]",    "webhook": { "endpoint": "https://..." }  }]

create_inbox

Create a new inbox. Domain is auto-resolved if not provided — no DNS setup needed.

delete_inbox

Delete an inbox permanently.

set_extraction_schema

Configure structured extraction for an inbox using a JSON Schema.

remove_extraction_schema

Remove structured extraction from an inbox.

Thread Tools

Threads are email conversations — groups of related messages. These are the most commonly used tools.

list_threads

List threads for an inbox with cursor-based pagination. Returns newest first by default.

Output:

{  "data": [    {      "thread_id": "conv_abc123",      "subject": "Order not received",      "message_count": 4,      "last_message_at": "2025-03-15T14:30:00Z",      "snippet": "Hi, I ordered 5 days ago and still haven't...",      "last_direction": "inbound",      "has_attachments": false    }  ],  "next_cursor": "eyJsYXN0...",  "has_more": true}

To get the next page, pass next_cursor as the cursor parameter.

get_thread_messages

Get all messages in a thread. Returns oldest first (chronological).

Output:

[  {    "message_id": "msg_001",    "direction": "inbound",    "participants": [      { "role": "sender", "identity": "[email protected]" },      { "role": "to", "identity": "[email protected]" }    ],    "content": "Hi, I placed order #4521 five days ago...",    "metadata": {      "subject": "Order not received",      "created_at": "2025-03-10T09:15:00Z"    }  },  {    "message_id": "msg_002",    "direction": "outbound",    "content": "We're looking into this for you...",    "metadata": {      "subject": "Re: Order not received",      "created_at": "2025-03-10T10:30:00Z"    }  }]

Search Tools

search_threads

Search across email threads by subject or content. Uses vector search (semantic) when available, falls back to text matching.

Triage Tools

Manage thread status, tags, and assignment — agent-native workflow primitives.

get_thread_metadata

Get triage metadata for a thread: tags, status, and assignment.

set_thread_status

Set the triage status of a thread.

tag_thread

Add tags/labels to a thread. Tags are additive — existing tags are preserved.

untag_thread

Remove tags from a thread.

assign_thread

Assign a thread to an agent or user. Pass empty to unassign.

Deliverability Tools

get_deliverability_stats

Get delivery metrics: sent, delivered, bounced, complained, failed counts and rates.

get_suppressions

List suppressed email addresses (bounces, complaints, unsubscribes).

get_delivery_events

Get delivery event log for tracking individual emails.

Message Tools

send_email

Send an email. Can send fresh emails or reply within an existing thread.

*Provide at least html or text.

To reply in a thread, pass the thread_id from list_threads or get_thread_messages. The email will be threaded in the recipient's mailbox.

Attachment Tools

upload_attachment

Upload a file. Returns an attachment_id to use with send_email.

Output:

{  "attachment_id": "att_abc123",  "filename": "report.pdf",  "mime_type": "application/pdf",  "size": 45230}

get_attachment_url

Get a temporary download URL for an attachment.

Output:

{  "url": "https://res.cloudinary.com/...",  "expires_in": 3600,  "filename": "report.pdf",  "mime_type": "application/pdf",  "size": 45230}

Phone Number Tools

Manage provisioned phone numbers for SMS.

list_phone_numbers

List all provisioned phone numbers in your account.

Parameters: None

get_phone_number

Get details for a single provisioned phone number.

list_available_phone_numbers

Browse available phone numbers before purchasing.

provision_phone_number

Purchase a phone number for SMS. Deducts credits from your balance.

update_phone_number

Update a phone number's friendly name or auto-reply message.

release_phone_number

Release a provisioned phone number back to the pool. No credit refund. Message history is retained.

set_phone_number_webhook

Configure a webhook for a phone number to receive SMS event notifications.

set_phone_number_allow_list

Set the allow list for a phone number — only these numbers can send SMS to it. Replaces existing list.

set_phone_number_block_list

Set the block list for a phone number — these numbers are rejected. Replaces existing list.

SMS Tools

send_sms

Send an SMS message.

list_sms_conversations

List SMS conversation threads.

get_sms_thread

Get all messages in an SMS thread with a specific number.

search_sms

Semantic search across SMS messages.

list_sms_suppressions

List phone numbers suppressed from receiving SMS (opted out via STOP keyword).

remove_sms_suppression

Remove a phone number from the SMS suppression list (re-enable SMS delivery).

Credits Tools

get_credit_balance

Get current credit balance for your Commune account.

Parameters: None

list_credit_bundles

List available credit bundles that can be purchased.

Parameters: None

credits_checkout

Create a Stripe checkout session to purchase a credit bundle.

FAQ

How do I add Commune to Claude Desktop? Edit ~/Library/Application Support/Claude/claude_desktop_config.json and add the commune MCP server block (see Setup above). Restart Claude Desktop. The Commune tools will appear in Claude's tool list automatically.

What's the difference between commune-mcp and the Python/TypeScript SDKs? commune-mcp is for interactive use in MCP clients like Claude Desktop or Cursor — you give natural language instructions and the AI calls the tools. The Python/TypeScript SDKs are for building autonomous agents programmatically in code. Both connect to the same Commune backend.

Does it work with Cursor's agent mode? Yes. Add commune-mcp to Cursor via Settings → MCP → Add Server using the JSON block shown in the Setup section. Once configured, Cursor's agent mode can use all Commune tools — reading threads, sending email, and managing inboxes — during any chat or Composer session.

How do I create a new inbox through the MCP server? Just ask: "Create a new inbox called support under example.com." The agent will call create_inbox with local_part: "support" and your domain ID. If you don't specify a domain, Commune auto-assigns one — so you can create an inbox with just a local part and no DNS configuration.

Can Claude actually send real emails through this? Yes. When the agent calls send_email, Commune delivers a real email via DKIM-signed SMTP to the recipient's inbox. The email appears exactly like a normal email — it threads correctly in Gmail and Outlook, supports HTML and attachments, and generates delivery events you can track.

What happens to emails that arrive while I'm not in a chat session? Commune stores all inbound emails and threads persistently. When you open a new chat and ask to check your inbox, the agent calls list_threads and retrieves everything that arrived since your last session. Optionally, you can configure a webhook on each inbox so your app gets notified in real-time (8 retries, HMAC-signed).

How do I reply in a thread instead of starting a new email? Pass the thread_id to send_email. The easiest way is to say "Reply to this thread saying..." after asking the agent to show you a thread — it will keep the thread_id in context and pass it automatically. The reply appears threaded in the recipient's email client.

Is my email content private? Your email content is transmitted over TLS and stored encrypted at rest on Commune's infrastructure. API keys authenticate every request, and webhooks are HMAC-signed so your app can verify the payload hasn't been tampered with. Your content is never used for training AI models.

Can I use this with my own email domain? Yes. Use create_domain to register your domain, then get_domain_records to see the required MX, TXT, and CNAME records, add them at your registrar, and call verify_domain. Once verified, all inboxes under that domain use your domain as the sender address (e.g. [email protected]).

What does the API key look like? Commune API keys start with the prefix comm_ followed by a random string — for example, comm_sk_live_abc123xyz. Create one from your Commune dashboard. Keep it secret: treat it like a password and never commit it to source control.

How do I search my inbox for a specific topic? Use the search_threads tool by asking naturally: "Search my support inbox for emails about refunds." The agent calls search_threads with your query. Commune uses semantic search, so it finds relevant threads even if the exact words don't match — for example, "money back" will surface threads about refunds.

Can multiple people use the same Commune MCP server? Yes. Commune uses organizations — multiple team members can share the same account and API key, or each member can have their own API key scoped to the same organization. All keys access the same domains and inboxes. For isolation between projects, create separate inboxes (e.g. billing@, support@) and filter by inbox_id in tool calls.

Environment Variables

Ecosystem

License

Apache-2.0