MCP Chess Server
By BINATI AInalytics
A Model Context Protocol (MCP) server that provides Chess.com player data integration. This server allows AI assistants like Claude to fetch real-time chess player profiles and statistics from Chess.com's public API.
Screenshots
Features
- Player Profile Lookup: Get detailed profile information for any Chess.com player
- Player Statistics: Retrieve comprehensive statistics including ratings, game counts, and performance metrics
- Error Handling: Robust error handling for API requests with detailed error messages
- Type Safety: Full type hints for better code quality and IDE support
Installation
Prerequisites
- Python >= 3.13
- uv (recommended) or pip for package management
Setup
- Clone the repository:
git clone https://github.com/CyprianFusi/mcp-chess-server.git
cd mcp_chess_server
- Install dependencies using uv:
uv sync
Or using pip:
pip install -e .
Usage
Running the Server
The server can be run directly using the installed command:
chess
Or via Python module:
python -m chess.server
Integration with Claude Desktop
To use this MCP server with Claude Desktop, add the following configuration to your Claude Desktop config file:
For MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
For Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"chess": {
"command": "uv",
"args": [
"--directory",
"/path/to/mcp_chess_server",
"run",
"chess.py"
]
}
}
}
Replace /path/to/mcp_chess_server with the actual path to your installation directory.
Alternatively, you can also integrate it directly from Github by updating claude desktop as follows:
"chess": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/CyprianFusi/mcp-chess-server.git",
"chess.py"
]
}
If this is your first MCP server then use this instead:
{
"mcpServers": {
"chess": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/CyprianFusi/mcp-chess-server.git",
"chess.py"
]
}
}
}
Available Tools
1. get_chess_player_profile
Retrieves the public profile for a Chess.com player.
Parameters:
player_name(str): The Chess.com username
Returns:
- Player profile information including:
- Username
- Player ID
- URL
- Name (if public)
- Country
- Location
- Join date
- Last online timestamp
- Followers count
- And more...
Example:
Get the profile for player "hikaru"
2. get_chess_player_stats
Retrieves comprehensive statistics for a Chess.com player.
Parameters:
player_name(str): The Chess.com username
Returns:
- Player statistics including:
- Current ratings for all game types (blitz, bullet, rapid, daily, etc.)
- Best ratings
- Win/loss/draw records
- Tactics rating
- Lessons stats
- Puzzle rush scores
Example:
Get the stats for player "magnuscarlsen"
Project Structure
mcp_chess_server/
├── src/
│ └── chess/
│ ├── __init__.py # Package initialization
│ ├── server.py # MCP server implementation
│ └── chess_api.py # Chess.com API client
├── assets/ # Screenshots and images
├── main.py # Entry point (legacy)
├── pyproject.toml # Project configuration
├── uv.lock # Dependency lock file
└── README.md # This file
Dependencies
- mcp[cli] (>=1.22.0): Model Context Protocol framework
- requests (>=2.32.5): HTTP library for API calls
- openai (>=2.8.1): OpenAI Python client
API Reference
This server uses the Chess.com Public API (https://api.chess.com/pub). No API key is required as it uses publicly available endpoints.
Error Handling
The server includes comprehensive error handling:
- Network timeouts (10 second timeout on requests)
- HTTP error responses
- Invalid player names
- API downtime
All errors are properly propagated with descriptive messages to help diagnose issues.
Development
Running Tests
# Install development dependencies
uv sync --dev
# Run tests (when available)
pytest
Code Quality
The codebase follows Python best practices:
- Type hints for all functions
- Comprehensive docstrings
- PEP 8 style guidelines
- Error handling on all API calls
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
This project is open source and available under the MIT License.
Acknowledgments
- Built with FastMCP
- Uses Chess.com Public API
Support
For issues, questions, or contributions, please open an issue on the GitHub repository.