Chess MXCP Server
An enterprise-grade Chess.com MCP server built with MXCP, featuring caching, analytics, audit trails, and advanced data analysis capabilities.
Features
🚀 Core Chess.com API Integration
- Player Tools: Profile, stats, online status, current games, game archives
- Game Tools: Monthly games, PGN downloads with caching
- Titled Players: List players by title (GM, IM, FM, etc.)
- Club Tools: Club profiles and member lists
💎 Enterprise Features (MXCP Advantages)
- Smart Caching: Configurable TTLs for different data types
- Rate Limiting: Token bucket algorithm to respect API limits
- Connection Pooling: Efficient HTTP client with keepalive
- Retry Logic: Automatic retries with exponential backoff
- Audit Trails: Track all API usage and queries
- Error Handling: Graceful degradation and detailed error messages
📊 Advanced Analytics (Not Available in Original)
- Rating Trends: Analyze player rating changes over time
- Game Analysis: Win/loss/draw patterns by time control and color
- Opening Statistics: Most played openings and success rates
- Activity Patterns: When players are most active
- Trending Players: Track popular players and follower growth
- SQL Query Access: Direct SQL access to cached data for custom analysis
🔐 Security & Governance
- Authentication Support: OAuth integration ready
- Audit Logging: Complete API call tracking
- Policy Engine: Fine-grained access control
- Type Safety: Comprehensive validation
Installation
- Install dependencies:
pip install httpx
- Initialize the database:
mxcp run tool get_player_profile --param username=hikaru
This will create the necessary cache tables automatically.
Usage
Start the Server
mxcp serve
Connect to Claude Desktop
The server_config.json was generated during mxcp init. Add it to your Claude Desktop configuration.
Example Queries
Ask Claude:
- "Get Magnus Carlsen's profile and analyze his rating trends"
- "Show me all GMs and their recent activity"
- "Analyze my opening repertoire" (after fetching games)
- "Compare win rates between blitz and rapid for a player"
- "Find trending chess players this week"
SQL Analytics
With SQL tools enabled, you can run custom queries:
- "Show me all cached games where I played the Sicilian Defense"
- "What's my performance on Tuesdays vs other days?"
- "List all players whose ratings improved by 100+ points"
Configuration
Edit mxcp-site.yml to adjust:
- Cache TTLs for different data types
- Rate limiting parameters
- Audit settings
- SQL tool permissions
Architecture
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Chess.com │ │ MXCP Server │ │ DuckDB Cache │
│ API │◄────│ - Rate Limiter │────►│ - API Cache │
│ │ │ - Retry Logic │ │ - Game Archive │
└─────────────────┘ │ - Type Safety │ │ - Analytics │
└──────────────────┘ └─────────────────┘
│
▼
┌──────────────────┐
│ LLM Client │
│ (Claude, etc) │
└──────────────────┘
Advanced Features
Caching Strategy
- Player profiles: 1 hour TTL
- Player stats: 30 minutes TTL
- Current games: 5 minutes TTL
- Game archives: 24 hours TTL (historical data)
- Titled players: 7 days TTL
- Individual games: Permanent cache
Analytics Tables
chess_api_cache: General API response cachechess_games_cache: Individual game storage with PGNplayer_profile_views: Track profile access patternsrating_history: Player rating changes over timeplayer_activity: Game count trackingaudit_log: Complete API usage audit trail
Development
Adding New Tools
- Create Python implementation in
python/ - Define tool in
tools/with YAML - Add SQL analytics if applicable
- Update cache tables if needed
Testing
# Test a specific tool
mxcp run tool get_player_profile --param username=hikaru
# Validate all tools
mxcp validate
# Check for drift
mxcp drift check
Why MXCP?
This implementation showcases how MXCP improves upon a basic MCP server:
- Performance: Caching reduces API calls by 90%+
- Analytics: SQL access enables complex analysis impossible with just API
- Reliability: Retry logic and rate limiting prevent failures
- Observability: Audit trails show exactly what's happening
- Extensibility: Easy to add new analytics without touching core code
- Type Safety: Validation prevents runtime errors
- Production Ready: Built for scale from day one
License
MIT