Intercom MCP
A Model Context Protocol (MCP) server for reading Intercom Help Center articles
Ask AI about Intercom MCP
Powered by Claude ยท Grounded in docs
I know everything about Intercom MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Intercom MCP Server
Intercom MCP server for Help Center content management and CS workflow automation.
Version
v0.7.0 - Added delete_article, create_collection, list_admins; optimized search_articles response
Features
Articles
- โ
get_article- Get a single article by ID - โ
list_articles- List articles with pagination - โ
search_articles- Search articles by keywords with highlighting support - โ
create_article- Create new articles with multilingual content - โ
update_article- Update existing articles with partial updates - โ
delete_article- Delete an article permanently
Collections
- โ
list_collections- List all Help Center collections - โ
get_collection- Get a single collection by ID - โ
update_collection- Update collection info and translations - โ
delete_collection- Delete a collection (permanent) - โ
create_collection- Create new Help Center collections
Admin
- โ
list_admins- List workspace admins (useful for finding valid author_id)
CS Workflow
- โ
reply_conversation- Reply to a conversation as an admin - โ
add_conversation_note- Add an internal note to a conversation - โ
close_conversation- Close a conversation - โ
update_ticket_state- Update a ticket's state
Installation
- Clone the repository:
git clone https://github.com/kaosensei/intercom-mcp.git
cd intercom-mcp
- Install dependencies:
npm install
- Build the project:
npm run build
Configuration
Get Intercom Access Token
- Go to Intercom Settings โ Developers โ Developer Hub
- Create a new app or use existing one
- Get an Access Token with Articles and Conversations read and write permissions
Environment Variables
| Variable | Required | Description |
|---|---|---|
INTERCOM_ACCESS_TOKEN | โ Always | Your Intercom API access token |
INTERCOM_ADMIN_ID | โ For CS tools | Admin ID used for reply_conversation and add_conversation_note when admin_id parameter is not provided |
Configure with Claude Code (Recommended)
If you're using Claude Code CLI, you can easily add the MCP server:
claude mcp add --transport stdio intercom-mcp \
--env INTERCOM_ACCESS_TOKEN=<your_token> \
--env INTERCOM_ADMIN_ID=<your_admin_id> \
-- node /ABSOLUTE/PATH/TO/intercom-mcp/dist/index.js
Replace:
<your_token>with your Intercom Access Token/ABSOLUTE/PATH/TO/with your actual project path
To verify it's configured:
claude mcp list
Configure Claude Desktop Manually
Alternatively, edit your Claude Desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Add this configuration:
{
"mcpServers": {
"intercom-mcp": {
"command": "node",
"args": [
"/ABSOLUTE/PATH/TO/intercom-mcp/dist/index.js"
],
"env": {
"INTERCOM_ACCESS_TOKEN": "your_intercom_access_token_here",
"INTERCOM_ADMIN_ID": "your_admin_id_here"
}
}
}
}
Important:
- Replace
/ABSOLUTE/PATH/TO/intercom-mcpwith your actual project path - Replace
your_intercom_access_token_herewith your actual token - Replace
your_admin_id_herewith your Intercom admin ID (required for CS tools)
Restart Claude Desktop
Completely quit Claude Desktop and restart it.
Usage
Once configured, you can use these commands in Claude Desktop:
List Articles
List Intercom articles
or
Show me the first 20 Intercom articles
Get Article Details
Get Intercom article with ID 9876543
Search Articles
Search for Intercom articles about "subscription"
or
Search published articles containing "ๆญๅฎข" with highlighted matches
or
Find articles with keyword "่จ้ฑ" in Chinese
Create Article
Create a new Intercom article titled "Getting Started Guide" with content "Welcome to our platform" by author ID 123456, save as draft
Update Article
Update article 9876543 and change its state to published
List Collections
List all Intercom Help Center collections
Get Collection
Get collection with ID 14608214
Update Collection
Update collection 14608214 and add Japanese translation
Delete Collection
Delete collection 16036040
Use Case: Translation Management
One of the key features of v0.4.0 is the ability to manage multilingual collections efficiently.
Add Missing Translations
You can easily add translations to collections that are missing certain languages:
Update collection 14608214 and add the missing Japanese translation: name "ใขใซใฆใณใ็ฎก็", description "ใขใซใฆใณใ่จญๅฎใ็ฎก็ใใ"
Bulk Translation Updates
Check which collections are missing translations:
List all collections and show me which ones are missing Japanese translations
Then update them one by one or create a plan to update multiple collections.
Verify Translations
After updating, verify the changes:
Get collection 14608214 and show me all available translations
Tools Reference
get_article
Get a single article by ID.
Parameters:
id(string, required): Article ID
Example:
{
"id": "9876543"
}
list_articles
List articles with pagination.
Parameters:
page(number, optional): Page number (default: 1)per_page(number, optional): Articles per page (default: 10, max: 50)
Example:
{
"page": 1,
"per_page": 20
}
search_articles
Search for articles using keywords. Supports full-text search across article content with multilingual support (English, Chinese, Japanese, etc.).
Parameters:
phrase(string, optional): Search keywords/phrase to find in articlesstate(string, optional): Filter by article state - "published", "draft", or "all" (default: "all")help_center_id(string, optional): Filter by specific Help Center ID
Example (Search by keyword):
{
"phrase": "subscription"
}
Example (List all drafts, no keyword needed):
{
"state": "draft"
}
Example (Chinese keyword search):
{
"phrase": "่จ้ฑๅถ",
"state": "all"
}
Response includes:
total_count: Total number of matching articlesarticles: Array of summary fields per article (id, title, description, state, url, author_id, created_at, updated_at, parent_id, parent_type)
Use get_article to fetch the full content of a specific article.
Use Cases:
- Find all articles about a specific topic
- Search for Chinese/Japanese content in multilingual help centers
- Locate articles that need updating
- Discover related content for cross-linking
create_article
Create a new article with multilingual support.
Parameters:
title(string, required): Article titlebody(string, required): Article content in HTML formatauthor_id(number, required): Author ID (must be a valid Intercom team member)description(string, optional): Article descriptionstate(string, optional): "draft" or "published" (default: "draft")parent_id(string, optional): Collection or section IDparent_type(string, optional): "collection" (default)translated_content(object, optional): Multilingual content
Example (Simple):
{
"title": "Getting Started Guide",
"body": "<p>Welcome to our platform</p>",
"author_id": 123456,
"state": "draft"
}
Example (Multilingual):
{
"title": "Getting Started Guide",
"body": "<p>Welcome to our platform</p>",
"author_id": 123456,
"state": "published",
"translated_content": {
"zh-TW": {
"title": "ๅ
ฅ้ๆๅ",
"body": "<p>ๆญก่ฟไฝฟ็จๆๅ็ๅนณๅฐ</p>",
"author_id": 123456,
"state": "published"
},
"ja": {
"title": "ในใฟใผใใฌใคใ",
"body": "<p>ใใฉใใใใฉใผใ ใธใใใใ</p>",
"author_id": 123456,
"state": "published"
}
}
}
update_article
Update an existing article. Only provided fields will be updated.
Parameters:
id(string, required): Article IDtitle(string, optional): Updated titlebody(string, optional): Updated contentdescription(string, optional): Updated descriptionstate(string, optional): "draft" or "published"author_id(number, optional): Updated author IDtranslated_content(object, optional): Updated translations
Example (Change state):
{
"id": "9876543",
"state": "published"
}
Example (Update content):
{
"id": "9876543",
"title": "Updated Title",
"body": "<p>Updated content</p>"
}
Example (Add translation):
{
"id": "9876543",
"translated_content": {
"zh-TW": {
"title": "ๆดๆฐ็ๆจ้ก",
"body": "<p>ๆดๆฐ็ๅ
งๅฎน</p>"
}
}
}
list_collections
List all Help Center collections (top-level categories).
Parameters:
page(number, optional): Page number (default: 1)per_page(number, optional): Collections per page (default: 50, max: 150)
Example:
{
"page": 1,
"per_page": 50
}
get_collection
Get a single collection by ID.
Parameters:
id(string, required): Collection ID
Example:
{
"id": "14608214"
}
update_collection
Update an existing collection. Only provided fields will be updated. Perfect for adding missing translations!
Parameters:
id(string, required): Collection IDname(string, optional): Updated collection name (updates default language)description(string, optional): Updated description (updates default language)parent_id(string, optional): Parent collection ID (null for top-level)translated_content(object, optional): Updated translations
Example (Update name and description):
{
"id": "14608214",
"name": "Account Management",
"description": "Manage your account settings"
}
Example (Add missing Japanese translation):
{
"id": "14608214",
"translated_content": {
"ja": {
"name": "ใขใซใฆใณใ็ฎก็",
"description": "ใขใซใฆใณใ่จญๅฎใ็ฎก็"
}
}
}
Example (Update multiple language translations):
{
"id": "14608214",
"translated_content": {
"ja": {
"name": "ใขใซใฆใณใ็ฎก็",
"description": "ใขใซใฆใณใ่จญๅฎใ็ฎก็ใใ"
},
"id": {
"name": "Manajemen Akun",
"description": "Kelola pengaturan akun Anda"
}
}
}
delete_collection
Delete a collection permanently. WARNING: This action cannot be undone!
Parameters:
id(string, required): Collection ID to delete
Example:
{
"id": "16036040"
}
โ ๏ธ Important Notes:
- Deleted collections cannot be restored
- All content within the collection may be affected
- Always backup important data before deletion
delete_article
Delete an article permanently. WARNING: This action cannot be undone!
Parameters:
id(string, required): Article ID to delete
Example:
{
"id": "9876543"
}
create_collection
Create a new Help Center collection.
Parameters:
name(string, required): Collection namedescription(string, optional): Collection descriptionparent_id(string, optional): Parent collection ID for nesting (omit for top-level)translated_content(object, optional): Multilingual content by locale code
Example (Simple):
{
"name": "Getting Started"
}
Example (With translation):
{
"name": "Getting Started",
"translated_content": {
"zh-TW": {
"name": "ๅ
ฅ้ๆๅ",
"description": "้ๅงไฝฟ็จๆๅ็ๅนณๅฐ"
}
}
}
list_admins
List all workspace admins. Useful for finding valid author_id values when creating or updating articles.
Parameters: None
Response includes:
id: Admin ID (use this asauthor_id)name: Display nameemail: Email addresshas_inbox_seat: Whether the admin has an inbox seat
reply_conversation
Reply to a conversation as an admin. The reply is visible to the customer.
Parameters:
conversation_id(string, required): The conversation ID to reply tobody(string, required): The reply message body (supports HTML)admin_id(string, optional): Admin ID to reply as (defaults toINTERCOM_ADMIN_IDenv var)
Example:
{
"conversation_id": "12345678",
"body": "<p>Thank you for reaching out. We'll look into this right away.</p>"
}
add_conversation_note
Add an internal note to a conversation. Notes are only visible to team members, not customers.
Parameters:
conversation_id(string, required): The conversation ID to add a note tobody(string, required): The note content (supports HTML)admin_id(string, optional): Admin ID adding the note (defaults toINTERCOM_ADMIN_IDenv var)
Example:
{
"conversation_id": "12345678",
"body": "<p>Customer has been refunded. Follow up in 3 days.</p>"
}
close_conversation
Close a conversation.
Parameters:
conversation_id(string, required): The conversation ID to close
Example:
{
"conversation_id": "12345678"
}
update_ticket_state
Update the state of a ticket.
Parameters:
ticket_id(string, required): The ticket ID to updatestate(string, required): The new ticket state โ one ofin_progress,waiting_on_customer,resolved
Example:
{
"ticket_id": "87654321",
"state": "resolved"
}
Development
Build
npm run build
Watch mode
npm run watch
Troubleshooting
Claude Desktop doesn't show the tools
- Check config file path is correct
- Verify JSON format (no trailing commas)
- Completely restart Claude Desktop
- Check absolute path to
dist/index.js
API errors
- Verify your Access Token is correct
- Ensure token has Articles read permissions
- Check Intercom API status
Build errors
- Ensure TypeScript version >= 5.0
- Delete
node_modulesanddist, then:
npm install && npm run build
Project Structure
intercom-mcp/
โโโ package.json # Project configuration
โโโ tsconfig.json # TypeScript configuration
โโโ src/
โ โโโ index.ts # Main server code
โโโ dist/ # Compiled output
โโโ README.md # This file
Roadmap
Completed
- โ Get Article (v0.1.0)
- โ List Articles (v0.1.0)
- โ Create Article (v0.2.0)
- โ Update Article (v0.2.0)
- โ Multilingual support for Articles (v0.2.0)
- โ List Collections (v0.3.1)
- โ Get Collection (v0.3.1)
- โ Update Collection (v0.4.0)
- โ Delete Collection (v0.4.0)
- โ Multilingual support for Collections (v0.4.0)
- โ Search Articles with keyword matching and highlighting (v0.5.0)
- โ Reply to conversations (v0.6.0)
- โ Add internal notes to conversations (v0.6.0)
- โ Close conversations (v0.6.0)
- โ Update ticket state (v0.6.0)
- โ Delete Article (v0.7.0)
- โ Create Collection (v0.7.0)
- โ List Admins (v0.7.0)
- โ Optimized search_articles response (v0.7.0)
Planned
- ๐ Batch operations
- ๐ Better error handling
- ๐ Modular file structure
Resources
License
MIT
