Skip to main content
Glama
Gelberm

Chess.com MCP Server

by Gelberm
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

Chess.com MCP Server

A Model Context Protocol (MCP) server that provides tools to interact with the Chess.com Public API. This server enables LLMs (like Claude) to fetch real-time player profiles and statistics.

Features

This server exposes the following tools:

  • get_chess_player_profile(username: str): Fetches the profile information of a Chess.com player (e.g., ID, URL, name, followers, country, last online status).

  • get_chess_player_stats(username: str): Fetches the detailed statistics of a player (e.g., current ratings for rapid, blitz, bullet, win/loss records).

Related MCP server: MCP Chess Server

Installation & Usage

You can use this server with any MCP-compatible client, such as the Claude Desktop App.

Method 1: Run directly from GitHub (Recommended)

You can run this server directly from the GitHub repository using uv (a fast Python package manager) without manually cloning the code.

Add the following configuration to your Claude Desktop config file:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "chess": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Gelberm/chess-mcp.git",
        "chess"
      ]
    }
  }
}

Available Tools

2 tools
get_chess_player_profileC
Get the profile of a chess.com player by username.
:param username: player username.
:return: player profile information.
ParametersJSON Schema
NameRequiredDescriptionDefault
usernameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. It only states that the tool 'gets' a profile and returns 'player profile information', without mentioning potential errors, rate limits, authentication requirements, or data format specifics. This is insufficient for a tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, with the purpose stated in the first sentence and docstring-style annotations for parameters and returns. It is appropriately sized for a simple tool, though it could include more guidance without becoming verbose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity, one parameter, and the presence of an output schema, the description covers the basic purpose and parameter. However, it lacks any contextual guidance about when to use this tool versus its sibling, and it does not disclose any behavioral details. For a tool with no annotations, this is a noticeable gap.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has no parameter descriptions (0% coverage), so the description must compensate. However, it merely restates the parameter as 'player username', adding no meaningful detail beyond the schema's 'username' string. It does not explain username format, case sensitivity, or any constraints, providing little value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get the profile') and the resource ('chess.com player by username'). It distinguishes from the sibling tool 'get_chess_player_stats' by focusing on 'profile' rather than 'stats', though it does not explicitly name the alternative. The purpose is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus the sibling 'get_chess_player_stats'. It does not mention any conditions, prerequisites, or exclusions. An agent would have to infer from the names which tool is appropriate, which is not reliable.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_chess_player_statsC
Get the statistics of a chess.com player by username.
:param username: player username.
:return: player statistics information.
ParametersJSON Schema
NameRequiredDescriptionDefault
usernameYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It indicates a read-only retrieval but does not mention any authentication requirements, rate limits, or error behaviors. The return value is vaguely described as 'player statistics information' without specifics, offering minimal transparency beyond the obvious.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is brief and front-loaded with the primary action. However, the docstring format adds redundant lines (':param' and ':return') that could be omitted without losing clarity. It is still concise and efficient, though not perfectly lean.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with an output schema, the return format need not be detailed, but the description offers only a vague 'player statistics information.' With no annotations and no usage guidance, an agent lacks context on error handling, edge cases (e.g., invalid usernames), or any prerequisites. This is insufficient for a complete picture, even for a simple get operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage for parameters, so the description must compensate. It includes a docstring line ':param username: player username' which merely repeats the property name and adds no additional meaning about format, constraints, or usage. This does not meaningfully aid the agent beyond what the schema already conveys.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Get the statistics') and resource ('chess.com player by username'), which distinguishes it from the sibling tool get_chess_player_profile by focusing on statistics rather than profile. It is specific but does not explicitly name the sibling, so it falls short of a perfect 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus the sibling get_chess_player_profile. The description only states what it does, not the conditions for choosing it over alternatives. This leaves the agent to infer usage from the tool name.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedget_chess_player_profile
    • First observedget_chess_player_stats
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one retrieves a player's profile information, the other retrieves their game statistics. There is no ambiguity about which tool to use based on the resource sought.

Naming Consistency5/5

Both tools follow the exact same get_chess_player_<resource> pattern, making the naming convention perfectly consistent and predictable. An agent can infer future tools would likely follow this pattern.

Tool Count3/5

At 2 tools, the server is at the borderline low end. While the tools are relevant, the server name 'Chess.com MCP Server' implies a broader domain, and this small count feels thin compared to the potential feature surface.

Completeness2/5

The server covers only profile and stats for a player, but omits many core Chess.com resources such as games, tournaments, leaderboards, or club information. Significant gaps remain that would require additional tools to handle common workflows.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Chess.com MCP Server

    pab1it0
    A
    license
    B
    quality
    B
    maintenance
    Provides access to Chess.com player data, game records, and public information through standardized MCP interfaces, allowing AI assistants to search and analyze chess information.
    10
    88
    MIT

  • MCP Chess Server

    Ramakrishna-Gedala
    F
    license
    B
    quality
    D
    maintenance
    Enables interaction with Chess.com's public API to retrieve player profiles and statistics including rating history and performance metrics for any Chess.com username.
    2
    -

  • MCP Chess Server

    CyprianFusi
    A
    license
    B
    quality
    D
    maintenance
    Provides Chess.com player data integration, enabling AI assistants to fetch real-time chess player profiles and comprehensive statistics including ratings, game counts, and performance metrics from Chess.com's public API.
    2
    MIT

  • Chess MCP Server

    bhayanak
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables AI assistants to explore player profiles, ratings, game archives, leaderboards, clubs, and puzzles via the Chess.com API.
    1
    MIT