FastIntercom MCP Server

High-performance Model Context Protocol (MCP) server for Intercom conversation analytics. Provides fast, local access to Intercom conversations through intelligent caching and background synchronization.

Features

• 🚀 Fast Local Access: Sub-100ms response times for conversation searches

• 🧠 Intelligent Sync: Request-triggered background updates ensure fresh data

• 💾 Efficient Storage: SQLite-based local storage (~2KB per conversation)

• 🔍 Powerful Search: Natural language timeframes and text search

• ⚡ MCP Integration: Direct integration with Claude Desktop and MCP clients

Quick Start

Installation

Setup

Claude Desktop Integration

Add to your Claude Desktop configuration (~/.config/claude/claude_desktop_config.json):

Usage

CLI Commands

MCP Tools

Once connected to Claude Desktop, you can ask questions like:

• "Search for conversations about billing in the last 7 days"

• "Show me customer conversations from yesterday"

• "What's the status of the FastIntercom server?"

• "Get conversation details for ID 123456789"

Configuration

Environment Variables

Configuration File

Located at ~/.fast-intercom-mcp/config.json:

Architecture

Intelligent Sync Strategy

FastIntercom uses a sophisticated caching strategy:

1. Immediate Response: MCP requests return data instantly from local cache

2. Background Sync: Stale timeframes trigger background updates

3. Smart Triggers: System learns from request patterns to optimize sync timing

4. Fresh Data: Next request gets updated data from background sync

Components

• Database: SQLite with optimized schema for fast searches

• Sync Service: Background service with intelligent refresh logic

• MCP Server: Model Context Protocol implementation

• CLI Interface: Command-line tools for management and monitoring

Development

Testing

Quick Tests

Comprehensive Testing

CI/CD Integration

• Fast Check: Runs on every PR (unit tests, linting, imports)

• Integration Test: Manual/weekly trigger with real API data

• Docker Test: On releases and deployment validation

For detailed testing procedures, see:

• docs/TESTING.md - Complete testing guide

• docs/INTEGRATION_TESTING.md - Integration test procedures

• scripts/README.md - Test script documentation

Local Development

Performance

Typical Performance Metrics

• Response Time: <100ms for cached queries

• Storage Efficiency: ~2KB per conversation average

• Sync Speed: 10-50 conversations/second

• Memory Usage: <100MB for server process

Storage Requirements

• Small workspace: 100-500 conversations, ~5-25 MB

• Medium workspace: 1,000-5,000 conversations, ~50-250 MB

• Large workspace: 10,000+ conversations, ~500+ MB

Troubleshooting

Common Issues

Connection Failed

• Verify your Intercom access token

• Check token permissions (read conversations required)

• Test: curl -H "Authorization: Bearer YOUR_TOKEN" https://api.intercom.io/me

Database Locked

• Stop any running FastIntercom processes: ps aux | grep fast-intercom-mcp

• Check log file: ~/.fast-intercom-mcp/logs/fast-intercom-mcp.log

MCP Server Not Responding

• Verify Claude Desktop config JSON syntax

• Restart Claude Desktop after configuration changes

• Check that the fast-intercom-mcp command is available in PATH

Debug Mode

API Reference

MCP Tools

search_conversations

Search conversations with flexible filters.

Parameters:

• query (string): Text to search in conversation messages

• timeframe (string): Natural language timeframe ("last 7 days", "this month", etc.)

• customer_email (string): Filter by specific customer email

• limit (integer): Maximum conversations to return (default: 50)

get_conversation

Get full details of a specific conversation.

Parameters:

• conversation_id (string, required): Intercom conversation ID

get_server_status

Get server status and statistics.

Parameters: None

sync_conversations

Trigger manual conversation sync.

Parameters:

• force (boolean): Force full sync even if recent data exists

Contributing

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

License

MIT License - see LICENSE file for details.

Support

• Issues: GitHub Issues

• Documentation: This README and inline code documentation

• Logs: Check ~/.fast-intercom-mcp/logs/fast-intercom-mcp.log for detailed information