Intercom Articles MCP Server

A Model Context Protocol (MCP) server for reading and writing Intercom Help Center articles.

Version

v0.5.0 - Added article search functionality with keyword matching and highlighting

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

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)

Installation

1. Clone the repository:

2. Install dependencies:

3. Build the project:

Configuration

Get Intercom Access Token

1. Go to Intercom Settings → Developers → Developer Hub

2. Create a new app or use existing one

3. Get an Access Token with Articles read and write permissions

Configure with Claude Code (Recommended)

If you're using Claude Code CLI, you can easily add the MCP server:

Replace:

• <your_token> with your Intercom Access Token

• /ABSOLUTE/PATH/TO/ with your actual project path

To verify it's configured:

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:

Important:

• Replace /ABSOLUTE/PATH/TO/intercom-articles-mcp with your actual project path

• Replace your_intercom_access_token_here with your actual token

Restart Claude Desktop

Completely quit Claude Desktop and restart it.

Usage

Once configured, you can use these commands in Claude Desktop:

List Articles

or

Get Article Details

Search Articles

or

or

Create Article

Update Article

List Collections

Get Collection

Update Collection

Delete Collection

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:

Bulk Translation Updates

Check which collections are missing translations:

Then update them one by one or create a plan to update multiple collections.

Verify Translations

After updating, verify the changes:

Tools Reference

get_article

Get a single article by ID.

Parameters:

• id (string, required): Article ID

Example:

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:

search_articles

Search for articles using keywords. Supports full-text search across article content with multilingual support (English, Chinese, Japanese, etc.).

Parameters:

• phrase (string, required): Search keywords/phrase to find in articles

• state (string, optional): Filter by article state - "published", "draft", or "all" (default: "all")

• help_center_id (string, optional): Filter by specific Help Center ID

• highlight (boolean, optional): Return highlighted matching content snippets (default: false)

Example (Simple search):

Example (Search with filters):

Example (Chinese keyword search):

Response includes:

• total_count: Total number of matching articles

• data.articles: Array of matching articles with full content

• pages: Pagination information with next page URL

• Highlighted content snippets (when highlight: true)

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 title

• body (string, required): Article content in HTML format

• author_id (number, required): Author ID (must be a valid Intercom team member)

• description (string, optional): Article description

• state (string, optional): "draft" or "published" (default: "draft")

• parent_id (string, optional): Collection or section ID

• parent_type (string, optional): "collection" (default)

• translated_content (object, optional): Multilingual content

Example (Simple):

Example (Multilingual):

update_article

Update an existing article. Only provided fields will be updated.

Parameters:

• id (string, required): Article ID

• title (string, optional): Updated title

• body (string, optional): Updated content

• description (string, optional): Updated description

• state (string, optional): "draft" or "published"

• author_id (number, optional): Updated author ID

• translated_content (object, optional): Updated translations

Example (Change state):

Example (Update content):

Example (Add translation):

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:

get_collection

Get a single collection by ID.

Parameters:

• id (string, required): Collection ID

Example:

update_collection

Update an existing collection. Only provided fields will be updated. Perfect for adding missing translations!

Parameters:

• id (string, required): Collection ID

• name (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):

Example (Add missing Japanese translation):

Example (Update multiple language translations):

delete_collection

Delete a collection permanently. WARNING: This action cannot be undone!

Parameters:

• id (string, required): Collection ID to delete

Example:

⚠️ Important Notes:

• Deleted collections cannot be restored

• All content within the collection may be affected

• Always backup important data before deletion

Development

Build

Watch mode

Troubleshooting

Claude Desktop doesn't show the tools

1. Check config file path is correct

2. Verify JSON format (no trailing commas)

3. Completely restart Claude Desktop

4. Check absolute path to dist/index.js

API errors

1. Verify your Access Token is correct

2. Ensure token has Articles read permissions

3. Check Intercom API status

Build errors

1. Ensure TypeScript version >= 5.0

2. Delete node_modules and dist, then:

Project Structure

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)

Planned

• 🔜 Delete Article

• 🔜 Batch operations

• 🔜 Better error handling

• 🔜 Modular file structure

Resources

• Intercom Articles API

• MCP TypeScript SDK

• MCP Documentation

License

MIT