# Intercom MCP Server

A hosted MCP server that gives AI agents full access to Intercom's core support workflows-search contacts, manage conversations, reply, assign, close tickets, and log notes.

Built on the [Model Context Protocol](https://modelcontextprotocol.io) using the official `@modelcontextprotocol/sdk`.

---

## Tools

| Tool | What it does |
|---|---|
| `search_contacts` | Find a contact by email, name, or phone |
| `create_or_update_contact` | Create a new contact or update an existing one |
| `search_conversations` | Filter conversations by status, contact, or assignee |
| `reply_to_conversation` | Send a customer reply or internal note |
| `close_conversation` | Resolve and close an open conversation |
| `assign_conversation` | Route a conversation to an admin or team |
| `create_contact_note` | Add an internal audit note to a contact's profile |

---

## Quickstart

### 1. Get your Intercom API token

1. Go to [app.intercom.com](https://app.intercom.com)
2. Navigate to **Settings → Developer Hub → Your App → Authentication**
3. Copy your **Access Token**

For testing, create a free developer workspace at [app.intercom.com/developers](https://app.intercom.com/developers) — no paid plan required.

---

### 2. Clone and install

```bash
git clone https://github.com/your-username/intercom-mcp-server.git
cd intercom-mcp-server
npm install
```

---

### 3. Set your environment variable

```bash
cp .env.example .env
```

Open `.env` and add your token:

```
INTERCOM_API_TOKEN=your_token_here
```

---

### 4. Connect to Claude Desktop

Add this to your Claude Desktop config file:

**Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "intercom": {
      "command": "node",
      "args": ["/absolute/path/to/intercom-mcp-server/index.js"],
      "env": {
        "INTERCOM_API_TOKEN": "your_token_here"
      }
    }
  }
}
```

Restart Claude Desktop. You should see the Intercom tools available.

---

### 5. Test with the MCP Inspector

```bash
npx @modelcontextprotocol/inspector node index.js
```

This opens a browser UI at `http://localhost:5173` where you can call each tool manually and inspect responses.

---

## Deployment on Railway

1. Push this repo to GitHub (private repo is fine)
2. Create a new project at [railway.app](https://railway.app)
3. Connect your GitHub repo — Railway auto-detects Node.js
4. Add environment variable: `INTERCOM_API_TOKEN = your_token`
5. Deploy — Railway gives you a public URL

---

## Environment Variables

| Variable | Required | Description |
|---|---|---|
| `INTERCOM_API_TOKEN` | Yes | Your Intercom Bearer token |

---

## Requirements

- Node.js 18 or higher
- An Intercom account (free developer workspace works for testing)

---

## License

MIT