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

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

• docs/TESTING.md - Complete testing guide
• docs/INTEGRATION_TESTING.md - Integration test procedures
• scripts/README.md - 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 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