Skip to content

commune-dev/commune-mcp

Repository files navigation

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 client
npx @smithery/cli install commune-dev/commune --client claude      # Claude Desktop
npx @smithery/cli install commune-dev/commune --client cursor      # Cursor
npx @smithery/cli install commune-dev/commune --client windsurf    # Windsurf
npx @smithery/cli install commune-dev/commune --client vscode      # VS Code
npx @smithery/cli install commune-dev/commune --client claude-code # Claude Code
npx @smithery/cli install commune-dev/commune --client cline       # Cline
npx @smithery/cli install commune-dev/commune --client roo-cline   # Roo Code
npx @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 alice@example.com 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_domainslist_inboxeslist_threads) You have 3 new threads in support@example.com:

  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 john@gmail.com 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 john@gmail.com 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 (support@yourdomain.com)
       |
       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.

Parameter Type Required Description
name str Yes Domain name (e.g. "example.com")
region str No AWS region (e.g. "us-east-1")

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.

Parameter Type Required Description
domain_id str Yes Domain ID from list_domains

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.

Parameter Type Required Description
domain_id str Yes Domain ID

Inbox Tools

Inboxes are mailboxes under a domain. support under example.comsupport@example.com.

list_inboxes

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

Parameter Type Required Description
domain_id str No Filter by domain (lists all if omitted)

Output:

[
  {
    "id": "i_xyz789",
    "localPart": "support",
    "address": "support@example.com",
    "webhook": { "endpoint": "https://..." }
  }
]

create_inbox

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

Parameter Type Required Description
local_part str Yes Part before @ (e.g. "support", "billing")
domain_id str No Domain to create under. Auto-resolved if omitted.
name str No Agent name for the inbox
display_name str No Sender display name shown in email clients
webhook_endpoint str No URL for email notifications

delete_inbox

Delete an inbox permanently.

Parameter Type Required Description
domain_id str Yes Domain ID
inbox_id str Yes Inbox ID

set_extraction_schema

Configure structured extraction for an inbox using a JSON Schema.

Parameter Type Required Description
domain_id str Yes Domain ID
inbox_id str Yes Inbox ID
name str Yes Schema name
schema str Yes JSON string of schema object
description str No Human-readable description
enabled bool No Enable extraction (default true)

remove_extraction_schema

Remove structured extraction from an inbox.

Parameter Type Required Description
domain_id str Yes Domain ID
inbox_id str Yes Inbox ID

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.

Parameter Type Required Description
inbox_id str One of these Filter by inbox
domain_id str required Filter by domain
limit int No 1–100, default 20
cursor str No Pagination cursor from previous response
order str No "desc" (newest first) or "asc"

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).

Parameter Type Required Description
thread_id str Yes Thread ID from list_threads
limit int No 1–1000, default 50
order str No "asc" (chronological) or "desc"

Output:

[
  {
    "message_id": "msg_001",
    "direction": "inbound",
    "participants": [
      { "role": "sender", "identity": "john@gmail.com" },
      { "role": "to", "identity": "support@example.com" }
    ],
    "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.

Parameter Type Required Description
query str Yes Search query (natural language)
inbox_id str One of these Filter by inbox
domain_id str required Filter by domain
limit int No 1–100, default 20

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.

Parameter Type Required Description
thread_id str Yes Thread ID

set_thread_status

Set the triage status of a thread.

Parameter Type Required Description
thread_id str Yes Thread ID
status str Yes "open", "needs_reply", "waiting", or "closed"

tag_thread

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

Parameter Type Required Description
thread_id str Yes Thread ID
tags str Yes Comma-separated tags (e.g. "urgent,vip,sales-lead")

untag_thread

Remove tags from a thread.

Parameter Type Required Description
thread_id str Yes Thread ID
tags str Yes Comma-separated tags to remove

assign_thread

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

Parameter Type Required Description
thread_id str Yes Thread ID
assigned_to str No Agent/user identifier (empty to unassign)

Deliverability Tools

get_deliverability_stats

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

Parameter Type Required Description
inbox_id str One of these Filter by inbox
domain_id str required Filter by domain
period str No "24h", "7d", "30d" (default: "7d")

get_suppressions

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

Parameter Type Required Description
inbox_id str No Filter by inbox
domain_id str No Filter by domain
limit int No Max results (default: 50)

get_delivery_events

Get delivery event log for tracking individual emails.

Parameter Type Required Description
message_id str No Filter for a specific message
inbox_id str No Filter by inbox
domain_id str No Filter by domain
event_type str No "sent", "delivered", "bounced", "complained", "failed"
limit int No Max results (default: 50)

Message Tools

send_email

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

Parameter Type Required Description
to str Yes Recipient(s), comma-separated for multiple
subject str Yes Subject line
html str No* HTML body
text str No* Plain text body
from_address str No Sender address
reply_to str No Reply-to address
thread_id str No Reply in existing thread
inbox_id str No Send from specific inbox
domain_id str No Send from specific domain
attachments str No Comma-separated attachment IDs

*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.

Parameter Type Required Description
content str Yes Base64-encoded file content
filename str Yes Filename (e.g. "report.pdf")
mime_type str Yes MIME type (e.g. "application/pdf")

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.

Parameter Type Required Description
attachment_id str Yes Attachment ID
expires_in int No Seconds until URL expires (default: 3600)

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.

Parameter Type Required Description
phone_number_id str Yes Phone number ID from list_phone_numbers

list_available_phone_numbers

Browse available phone numbers before purchasing.

Parameter Type Required Description
type str No "TollFree" (default) or "Local"
country str No Two-letter country code (default: "US")
limit int No Max results (default: 10)

provision_phone_number

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

Parameter Type Required Description
phone_number str No Specific E.164 number to buy (auto-selected if omitted)
type str No "tollfree" (default) or "local"
friendly_name str No Human-readable label

update_phone_number

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

Parameter Type Required Description
phone_number_id str Yes Phone number ID
friendly_name str No Human-readable label
auto_reply str No Auto-reply text for all inbound SMS (empty string to disable)

release_phone_number

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

Parameter Type Required Description
phone_number_id str Yes Phone number ID to release

set_phone_number_webhook

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

Parameter Type Required Description
phone_number_id str Yes Phone number ID
endpoint str Yes HTTPS URL to receive webhook payloads
secret str No Webhook signing secret for payload verification
events list No Event types (default: ["sms.received", "sms.sent"])

set_phone_number_allow_list

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

Parameter Type Required Description
phone_number_id str Yes Phone number ID
numbers list Yes E.164 phone numbers to allow (empty list to clear)

set_phone_number_block_list

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

Parameter Type Required Description
phone_number_id str Yes Phone number ID
numbers list Yes E.164 phone numbers to block (empty list to clear)

SMS Tools

send_sms

Send an SMS message.

Parameter Type Required Description
to str Yes Recipient in E.164 format (e.g. "+15551234567")
body str Yes SMS message text
phone_number_id str No Send from a specific phone number (auto-assigned if omitted)

list_sms_conversations

List SMS conversation threads.

Parameter Type Required Description
phone_number_id str No Filter by phone number (lists all if omitted)
limit int No 1–100, default 20

get_sms_thread

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

Parameter Type Required Description
remote_number str Yes External phone number in E.164 format
phone_number_id str Yes Your Commune phone number ID

search_sms

Semantic search across SMS messages.

Parameter Type Required Description
query str Yes Search query
phone_number_id str No Scope to a specific phone number
limit int No 1–100, default 20

list_sms_suppressions

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

Parameter Type Required Description
phone_number_id str No Filter by phone number (lists all if omitted)

remove_sms_suppression

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

Parameter Type Required Description
phone_number str Yes E.164 phone number to remove from suppressions

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.

Parameter Type Required Description
bundle str Yes Bundle ID: "starter", "growth", or "scale"
return_url str No URL to redirect to after payment

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. support@yourdomain.com).

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

Variable Required Description
COMMUNE_API_KEY Yes Your API key (starts with comm_)
COMMUNE_BASE_URL No Override API URL (default: Commune cloud)

Ecosystem

Package Description
commune Email & SMS infrastructure — self-hostable backend
commune-ai TypeScript/Node.js SDK
commune-python Python SDK
commune-mcp MCP server for Claude Desktop, Cursor, Windsurf
commune-cli Command-line interface

License

Apache-2.0

About

Email & SMS for Claude Desktop, Cursor, and Windsurf. 13 tools: create inboxes, send email, read threads, provision phone numbers, send SMS. Install in 30s.

Topics

Resources

License

Stars

Watchers

Forks

Packages

 
 
 

Contributors