SalvatoreDiPalo/chess-mcp-server

Chess MCP Server

A Model Context Protocol (MCP) server that provides seamless access to Chess.com API data through AI assistants like Claude, ChatGPT, and others.

MCP Resources

• Official Documentation: Model Context Protocol
• GitHub Repository: modelcontextprotocol
• Specification: MCP Specification

Project Architecture

This Chess MCP Server provides three main tools:

1. getPlayerProfile - Retrieve player information and statistics
2. getPlayerStats - Get detailed player ratings and performance data
3. getDailyPuzzle - Access the daily chess puzzle

Quick Start

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn package manager

Installation

1. Clone the repository

   git clone https://github.com/dipalosalvatore/chess-mcp-server.git
   cd chess-mcp-server
   

2. Install dependencies

   npm install
   

3. Build the project

   npm run build
   

4. Start the server

   npm start
   

Docker Support

Using Docker

1. Build the Docker image

   docker build -t chess-mcp-server .
   

2. Run the container

   docker run -it chess-mcp-server
   

Docker Configuration for MCP Clients

When using Docker, update your MCP client configuration to use the Docker container:

Claude Desktop with Docker

{
  "mcpServers": {
    "chess": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "chess-mcp-server"],
      "env": {}
    }
  }
}

MCP Configuration

For Claude Desktop

1. Open Claude Desktop settings
2. Navigate to "Servers" section
3. Add a new server with these settings:

{
  "name": "Chess MCP Server",
  "command": "node",
  "args": ["/path/to/chess-mcp-server/dist/index.js"],
  "env": {}
}

For Other MCP Clients

Most MCP clients support similar configuration. The server communicates via stdin/stdout, so you'll need to specify:

• Command: node
• Arguments: [path-to-dist/index.js]
• Working Directory: Your project directory

Example Configuration Files

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "chess": {
      "command": "node",
      "args": ["/Users/username/projects/chess-mcp-server/dist/index.js"],
      "env": {}
    }
  }
}

ChatGPT (if supported)

{
  "servers": [
    {
      "name": "Chess Server",
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/chess-mcp-server"
    }
  ]
}

Available Tools

1. Get Player Profile

Retrieves comprehensive player information from Chess.com.

Tool Name: getPlayerProfile

Parameters:

• username (string, required): Chess.com username

Example Usage:

Get the profile for player "magnuscarlsen"

2. Get Player Stats

Retrieves detailed player statistics and ratings.

Tool Name: getPlayerStats

Parameters:

• username (string, required): Chess.com username

Example Usage:

Get statistics for player "hikaru"

3. Get Daily Puzzle

Retrieves the current daily puzzle from Chess.com.

Tool Name: getDailyPuzzle

Parameters: None

Example Usage:

Get today's chess puzzle

Development

Building from Source

# Install dependencies
npm install

# Type checking
npm run type-check

# Build the project
npm run build

Project Structure Details

Chess API Wrapper (src/chess/)

The chess API is organized into specialized classes:

• PlayerApi - Player profiles, stats, and game history
• PuzzleApi - Daily puzzles and random puzzles
• CommunityApi - Clubs, tournaments, and teams
• BaseChessApi - Common functionality and HTTP client setup

MCP Tools (src/tools/)

Each tool is implemented as a function that:

1. Validates input using Zod schemas
2. Calls the appropriate Chess.com API
3. Returns standardized MCP responses
4. Handles errors gracefully

Error Handling

The server provides comprehensive error handling:

• Validation Errors (400) - Invalid input parameters
• Not Found Errors (404) - Player or resource not found
• Rate Limit Errors (429) - API rate limit exceeded
• Server Errors (5xx) - Chess.com API issues

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Development Setup

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

This project is licensed under the MIT License - see the file for details.

Acknowledgments

• Chess.com for providing the API
• Model Context Protocol for the MCP standard
• Anthropic for Claude and MCP support