MCP Server

Overview

The Pigeons MCP (Model Context Protocol) server exposes Pigeons operations as tools that LLM agents can call. This lets Claude, GPT, and other agents send emails, manage contacts, read inboxes, and run campaigns through natural language.

Install

npm install -g @pigeons/mcp

Configure in Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "pigeons": {
      "command": "npx",
      "args": ["-y", "@pigeons/mcp", "--url", "https://pigeons.yourdomain.com", "--api-key", "pgn_your_key_here"]
    }
  }
}

Or use environment variables:

{
  "mcpServers": {
    "pigeons": {
      "command": "npx",
      "args": ["-y", "@pigeons/mcp"],
      "env": {
        "PIGEONS_URL": "https://pigeons.yourdomain.com",
        "PIGEONS_API_KEY": "pgn_your_key_here"
      }
    }
  }
}

Configure in Claude Code

Add to your project's .claude/settings.json or global settings:

{
  "mcpServers": {
    "pigeons": {
      "command": "npx",
      "args": ["-y", "@pigeons/mcp"],
      "env": {
        "PIGEONS_URL": "https://pigeons.yourdomain.com",
        "PIGEONS_API_KEY": "pgn_your_key_here"
      }
    }
  }
}

Available Tools

Email tools

ToolDescription
send_emailSend a transactional email with HTML/text or a template
get_emailGet email details and delivery status by ID
list_emailsList sent emails with optional status filtering

Inbox tools

ToolDescription
create_inboxCreate a new agent inbox with a real email address
list_inboxesList all agent inboxes
get_inbox_messagesGet messages for an inbox, optionally filtered by thread or direction
get_threadGet a full conversation thread
reply_to_messageSend a reply from an inbox, maintaining the conversation thread
update_thread_statusUpdate thread status (open, closed, snoozed)

Contact tools

ToolDescription
create_contactCreate a new contact
search_contactsList contacts with tag or email filtering
update_contactUpdate a contact's properties, tags, or name

Template tools

ToolDescription
list_templatesList available email templates
preview_templateRender a template with sample data

Campaign tools

ToolDescription
create_campaignCreate a draft email campaign
list_campaignsList campaigns with optional status filter
get_campaignGet campaign details and statistics
send_campaignSend or schedule a campaign
cancel_campaignCancel a sending or scheduled campaign

Sequence tools

ToolDescription
create_sequenceCreate a multi-step email sequence
list_sequencesList sequences
get_sequenceGet sequence details with steps and stats
activate_sequenceActivate a sequence
pause_sequencePause an active sequence
enroll_in_sequenceEnroll a contact in a sequence

Topic tools

ToolDescription
create_topicCreate a subscription topic
list_topicsList subscription topics
get_topicGet topic details
delete_topicDelete a topic

Resources

The MCP server also exposes read-only resources:

Resource URIDescription
pigeons://inboxesAll agent inboxes and their email addresses
pigeons://templatesAvailable templates with slugs and variable schemas
pigeons://domainsVerified sending domains and their status

Example Prompts

Once configured, you can ask your LLM agent:

  • "Send a welcome email to alice@example.com using the welcome-email template"
  • "Check the status of email msg_abc123"
  • "Show me all undelivered emails from today"
  • "Create an inbox for support@mycompany.com"
  • "Read the latest messages in the support inbox"
  • "Reply to the customer in thread thr_xyz saying we'll look into it"
  • "Create a campaign called 'Product Launch' targeting contacts tagged with 'beta'"
  • "What are the delivery stats for the Product Launch campaign?"
  • "Create an onboarding sequence with a welcome email, 1-day delay, then a getting-started email"
  • "Enroll contact ctc_abc123 in the onboarding sequence"