Intercom MCP Server

An open-source Model Context Protocol (MCP) integration for Intercom, built to work with Claude Desktop. It exposes your Intercom workspace as a set of AI-queryable tools and delivers a fully formatted daily customer support report to your inbox every morning — no third-party AI API required.

Overview

Architecture

Claude Desktop
    │
    └── intercom_bridge.py   (local — stdio ↔ SSE)
            │
            └──► Remote Server:3004/sse   (intercom_mcp_server.py)
                        │
                        └──► Intercom REST API  (api.intercom.io)

Daily Report Scheduler  (daily_report.py)
    └──► Intercom REST API → HTML Report → SMTP → your inbox

Why not use the official Intercom MCP server?
The official server at mcp.intercom.com only supports US-hosted Intercom workspaces. This project calls the Intercom REST API directly, so it works globally for all workspace regions.

Features

MCP Tools (available to Claude Desktop)

Daily Email Report

Sent every morning at a configurable time (default 08:00 UTC). Includes:

• At a Glance — 8 key metrics: total, closed, open, resolution rate, handled, no-response, reopened, avg. time to close

• Channel Breakdown — Email vs Live Chat vs Admin Initiated with progress bars

• Topic Breakdown — Auto-categorised by keyword: Billing, Payouts, Account Access, Technical Issues, Compliance, Evaluation, General Enquiry

• Agent Performance — Leaderboard ranked by conversations closed, with avg. exchanges and reopen counts per agent

• Key Insights — Auto-generated observations based on the day's data

The report is generated with pure Python — no external AI API dependency.

Deployment

Prerequisites

• Python 3.10+

• Docker (for remote server deployment)

• An Intercom workspace with an API access token

• An SMTP account for sending the daily report (e.g. Gmail with an App Password)

1. Clone the repository

git clone https://github.com/YOUR_USERNAME/intercom-mcp-server.git
cd intercom-mcp-server

2. Configure environment variables

cp .env.example .env

Edit .env with your values (see Environment Variables below). Never commit .env — it is in .gitignore.

3. Deploy the MCP server (remote host / EC2)

Copy all files (excluding .env) to your server, then:

# On the server
cd ~/intercom-mcp-server

# Build the Docker image
sudo docker build -t intercom-mcp-server .

# Start the MCP server
sudo docker run -d \
  --name intercom-mcp-server \
  --restart unless-stopped \
  -p 3004:3004 \
  --env-file .env \
  intercom-mcp-server python intercom_mcp_server.py

# Start the daily report scheduler
sudo docker run -d \
  --name intercom-daily-report \
  --restart unless-stopped \
  --env-file .env \
  intercom-mcp-server python daily_report.py

4. Open the port

In your cloud provider's firewall / security group, open TCP port 3004 (inbound) for the MCP server. Restrict to your team's IP range where possible.

5. Verify the server is healthy

curl http://YOUR_SERVER_IP:3004/health
# Expected: {"status": "healthy", "server": "intercom-mcp"}

6. Trigger a test report

sudo docker exec intercom-daily-report python daily_report.py --now

Environment Variables

Copy .env.example to .env and fill in the values below. Do not commit the .env file.

# ── Intercom ──────────────────────────────────────────────────────────
# Get from: Intercom Settings > Developers > Access Tokens
INTERCOM_API_TOKEN=your_intercom_access_token

# ── Daily Report ──────────────────────────────────────────────────────
# Comma-separated list of recipient email addresses
REPORT_RECIPIENTS=you@yourcompany.com

# Time to send the report each day (24-hour HH:MM, UTC)
REPORT_SEND_TIME=08:00

# ── SMTP ──────────────────────────────────────────────────────────────
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587

# Sender credentials (Gmail: use an App Password, not your account password)
EMAIL_1_ADDRESS=reports@yourcompany.com
EMAIL_1_PASSWORD=xxxx xxxx xxxx xxxx
EMAIL_1_DISPLAY_NAME=Support Reports

# ── MCP Server (optional overrides) ───────────────────────────────────
# MCP_HOST=0.0.0.0
# MCP_PORT=3004
# INTERCOM_MCP_SSE_URL=http://YOUR_SERVER_IP:3004/sse

Getting an Intercom API token

1. In Intercom, go to Settings → Developers → Access Tokens

2. Create a token with at minimum these scopes: Read conversations, Read contacts, Read admins, Read tags

3. Paste the token into .env as INTERCOM_API_TOKEN

Gmail App Password (for SMTP)

If using Gmail as the SMTP sender:

1. Enable 2-Step Verification on the Google account

2. Go to Google Account → Security → App Passwords

3. Generate an app password for "Mail"

4. Use that 16-character password as EMAIL_1_PASSWORD (spaces are fine)

Claude Desktop Setup

Do this on every machine that will use the Intercom tools in Claude.

Prerequisites

• Claude Desktop installed

• Python 3.10+ available on the machine

• pip install requests python-dotenv

Steps

1. Save the bridge script

mkdir -p ~/mcp-bridges
# Copy intercom_bridge.py from this repo to that folder
cp intercom_bridge.py ~/mcp-bridges/

2. Set the remote server URL (if not using the default)

Either set the environment variable before running, or edit intercom_bridge.py line:

SSE_URL = "http://YOUR_SERVER_IP:3004/sse"

3. Edit Claude Desktop config

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the intercom entry to mcpServers:

{
  "mcpServers": {
    "intercom": {
      "command": "python3",
      "args": ["/Users/YOUR_NAME/mcp-bridges/intercom_bridge.py"]
    }
  }
}

4. Restart Claude Desktop — quit fully (Cmd+Q on Mac), then reopen.

5. Verify — ask Claude:

"List all admins in our Intercom workspace"

Example Prompts for Claude

Workspace overview

"Give me a summary of our Intercom support for the last 7 days — total conversations, open vs closed, and average response times."

Drill into specific tickets

"Find all open Intercom conversations about withdrawals from this week."

Look up a customer

"Find the Intercom contact for john@example.com and show me their recent conversations."

Team performance

"Which agent closed the most conversations yesterday in Intercom?"

On-demand report

"Pull today's Intercom stats and give me a full breakdown by channel and topic."

Services at a Glance

Project Structure

intercom-mcp-server/
├── intercom_mcp_server.py   # SSE MCP server — 7 Intercom tools
├── intercom_bridge.py       # Local stdio↔SSE bridge for Claude Desktop
├── daily_report.py          # Scheduled daily report generator + emailer
├── requirements.txt         # Python dependencies
├── Dockerfile               # Docker image definition
├── docker-compose.yml       # Optional: orchestrate both containers
├── .env.example             # Environment variable template (safe to commit)
└── .gitignore               # Ensures .env is never committed

Contributing

Pull requests are welcome. For major changes, please open an issue first.

License

MIT