fast-intercom-mcp

evolsb/fast-intercom-mcp

3.2

If you are the rightful owner of fast-intercom-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

FastIntercom MCP Server is a high-performance server designed for efficient Intercom conversation analytics, providing fast local access through intelligent caching and background synchronization.

Tools

  1. search_conversations

    Search conversations with flexible filters.

  2. get_conversation

    Get full details of a specific conversation.

  3. get_server_status

    Get server status and statistics.

  4. sync_conversations

    Trigger manual conversation sync.

FastIntercom MCP Server

Fast Check

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

# Clone and install
git clone <repository-url>
cd fast-intercom-mcp
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Setup

# Initialize with your Intercom credentials
fast-intercom-mcp init

# Check status
fast-intercom-mcp status

# Sync conversation history
fast-intercom-mcp sync --force --days 7

Claude Desktop Integration

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

{
  "mcpServers": {
    "fast-intercom-mcp": {
      "command": "fast-intercom-mcp",
      "args": ["start"],
      "env": {
        "INTERCOM_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}

Usage

CLI Commands

fast-intercom-mcp status              # Show server status and statistics
fast-intercom-mcp sync                # Incremental sync of recent conversations  
fast-intercom-mcp sync --force --days 7  # Force sync last 7 days
fast-intercom-mcp start               # Start MCP server
fast-intercom-mcp logs                # View recent log entries
fast-intercom-mcp reset               # Reset all data

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

INTERCOM_ACCESS_TOKEN=your_token_here
FASTINTERCOM_LOG_LEVEL=INFO
FASTINTERCOM_MAX_SYNC_AGE_MINUTES=5
FASTINTERCOM_BACKGROUND_SYNC_INTERVAL=10

Configuration File

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

{
  "log_level": "INFO",
  "max_sync_age_minutes": 5,
  "background_sync_interval_minutes": 10,
  "initial_sync_days": 30
}

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
# Unit tests
pytest tests/

# Integration test (requires API key)
./scripts/run_integration_test.sh

# Docker test
./scripts/test_docker_install.sh
Comprehensive Testing
# Full unit test suite with coverage
pytest tests/ --cov=fast_intercom_mcp

# Integration test with performance report
./scripts/run_integration_test.sh --performance-report

# Docker clean install test
./scripts/test_docker_install.sh --with-api-test

# Performance benchmarking
./scripts/run_performance_test.sh
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:

  • - Complete testing guide
  • - Integration test procedures
  • - Test script documentation

Local Development

# Install in development mode
pip install -e .

# Run with verbose logging
fast-intercom-mcp --verbose status

# Monitor logs in real-time
tail -f ~/.fast-intercom-mcp/logs/fast-intercom-mcp.log

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

fast-intercom-mcp --verbose start    # Enable verbose logging
export FASTINTERCOM_LOG_LEVEL=DEBUG  # Set debug level

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 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