FastIntercom

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

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

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

# 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

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

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

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"

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

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

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

FastIntercom uses a sophisticated caching strategy:
- Immediate Response: MCP requests return data instantly from local cache
- Background Sync: Stale timeframes trigger background updates
- Smart Triggers: System learns from request patterns to optimize sync timing
- Fresh Data: Next request gets updated data from background sync

- 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

# Unit tests pytest tests/ # Integration test (requires API key) ./scripts/run_integration_test.sh # Docker test ./scripts/test_docker_install.sh

# 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

- 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

- docs/TESTING.md- Complete testing guide
- docs/INTEGRATION_TESTING.md- Integration test procedures
- scripts/README.md- Test script documentation

# 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

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

MIT License - seeLICENSEfile for details.

- Issues:GitHub Issues
- Documentation: This README and inline code documentation
- Logs: Check~/.fast-intercom-mcp/logs/fast-intercom-mcp.logfor detailed information

Centralized management of RePricing for Amazon, eBay, and Kaufland, Lost & Found for Amazon FBA, and integrated HelpDesk.