Skip to main content
Glama
Unofficial WCA MCP Server

Unofficial WCA MCP Server

by YuchengMaUTK

Unofficial WCA MCP Server

English | 中文


An unofficial Model Context Protocol (MCP) server for World Cube Association (WCA) data.

This server provides tools to access data from the official WCA v0 API using large language models via the MCP protocol.

🔄 API Migration Notice

We recently migrated this server to use the Official WCA v0 API. Previously, it relied on an unofficial third-party API that has since become unstable and undocumented. The official WCA API ensures much better stability, reliable uptime, and guaranteed accuracy directly from the source. This migration guarantees long-term support for fetching competitor profiles, competition results, and world records.

✨ Features

  • Built with FastMCP: Runs blazing fast using the fastmcp Python framework.

  • Competitor Information: Look up WCA ID, personal records, medals, and competition history.

  • Competition Data: Search for competitions, get competition details, and retrieve competition results.

  • Records: Access the current world/continental/national records for all standard WCA events.

  • Countries: List all recognized WCA countries and their continent mappings.

🛠️ Available Tools

The server exposes the following MCP tools for LLM use:

  • get_wca_countries: Get a list of all recognized WCA countries, their continent IDs, and ISO2 codes.

  • get_person_by_wca_id: Get detailed information about a specific speedcuber (records, medals, competition count).

  • search_persons: Search the database for competitors by name (e.g., "Yucheng Ma").

  • get_records: Get current world, continental, and national records (can be filtered by event like "333").

  • search_competitions: Search for competitions by name, country (ISO2), or date range.

  • get_competition_by_id: Retrieve full metadata for a specific competition.

  • get_competition_results: Get the results of a competition, optionally filtered by event ID.

💡 Example Prompts

Here are some examples of what you can ask Claude when this MCP server is connected:

  • "How are the rubik's cube competition results for Yucheng Ma?"

  • "Who holds the current world record for 3x3 blindfolded?"

  • "When and where is the next WCA competition in Germany?"

  • "What are the personal records for WCA ID 2015KLEE01 across all events?"

  • "Can you show me the podium results for the Rubik's WCA World Championship 2023?"

📦 Installation

This server uses uv for dependency management.

# Clone the repository
git clone https://github.com/YuchengMaUTK/unofficial-wca-mcp-server.git
cd unofficial-wca-mcp-server

# Install dependencies using uv
uv sync

⚙️ Setup for Claude Desktop

You can configure this MCP server to work directly inside Claude Desktop by updating your claude_desktop_config.json file.

Windows path: %APPDATA%\Claude\claude_desktop_config.json
Mac path: ~/Library/Application Support/Claude/claude_desktop_config.json

Add the following inside your mcpServers object:

{
  "mcpServers": {
    "wca": {
      "command": "path/to/unofficial-wca-mcp-server/.venv/Scripts/python.exe",
      "args": [
        "-m",
        "wca_mcp_server"
      ]
    }
  }
}

(Make sure to adjust the python executable path to match your environment's .venv directory based on your OS).


一个用于获取世界魔方协会 (WCA) 数据的非官方模型上下文协议 (MCP) 服务器。

本服务器提供了多种工具,使大型语言模型能够通过 MCP 协议访问 官方 WCA v0 API 的数据。

🔄 API 迁移说明

我们最近将此服务器迁移到了 官方 WCA v0 API。以前,它依赖于一个非官方的第三方 API,但该 API 后来变得不稳定且缺乏文档支持。官方 WCA API 能够确保更好的稳定性、可靠的正常运行时间,并直接提供来源准确的数据。此次迁移保证了对获取选手资料、比赛结果和世界纪录的长期支持。

✨ 主要功能

  • 基于 FastMCP 构建:使用 fastmcp Python 框架运行,速度极快。

  • 选手信息:查询 WCA ID、个人最好成绩 (PR)、奖牌和参赛历史。

  • 比赛数据:搜索比赛、获取比赛详情和检索比赛成绩。

  • 各项纪录:访问所有标准 WCA 项目的当前世界/洲际/国家纪录。

  • 国家/地区:列出所有受 WCA 认可的国家/地区及其所属大洲映射。

🛠️ 可用工具

服务器为大语言模型 (LLM) 开放了以下 MCP 工具:

  • get_wca_countries:获取所有受 WCA 认可的国家/地区列表及其大洲 ID 和 ISO2 代码。

  • get_person_by_wca_id:获取特定魔方选手的详细信息(成绩、奖牌、参赛次数)。

  • search_persons:按名称在数据库中搜索选手(例如,"Yucheng Ma")。

  • get_records:获取当前的世界、洲际和国家纪录(可按项目过滤,如 "333")。

  • search_competitions:按名称、国家/地区 (ISO2) 或日期范围搜索比赛。

  • get_competition_by_id:检索特定比赛的完整元数据。

  • get_competition_results:获取比赛结果,可选择按项目 ID 过滤。

💡 提问示例

下面展示了在连接此 MCP 服务器后,你可以向 Claude 提问的一些示例:

  • "Yucheng Ma 选手的魔方比赛成绩怎么样?"

  • "目前三阶盲拧的世界纪录保持者是谁?"

  • "德国下一场 WCA 比赛是什么时候,在哪里举办?"

  • "WCA ID 为 2015KLEE01 的选手在所有项目中的个人最好成绩是什么?"

  • "你能帮我查一下 2023 年 WCA 世界锦标赛的领奖台结果吗?"

📦 安装

本服务器使用 uv 进行依赖管理。

# 克隆仓库
git clone https://github.com/YuchengMaUTK/unofficial-wca-mcp-server.git
cd unofficial-wca-mcp-server

# 使用 uv 安装依赖
uv sync

⚙️ Claude Desktop 配置

你可以通过更新 claude_desktop_config.json 文件,将此 MCP 服务器配置为直接在 Claude Desktop 中工作。

Windows 路径: %APPDATA%\Claude\claude_desktop_config.json
Mac 路径: ~/Library/Application Support/Claude/claude_desktop_config.json

在你的 mcpServers 对象中添加以下内容:

{
  "mcpServers": {
    "wca": {
      "command": "path/to/unofficial-wca-mcp-server/.venv/Scripts/python.exe",
      "args": [
        "-m",
        "wca_mcp_server"
      ]
    }
  }
}

(请确保根据你的操作系统调整 python 可执行文件路径,使其与你环境中的 .venv 目录匹配).

📄 许可证

本项目未与世界魔方协会 (WCA) 建立官方合作关系。API 的使用必须遵守 WCA API 服务条款。

Available Tools

12 tools
get_championship_detailsA

Get detailed information about a specific championship by its ID.

Returns comprehensive information about a WCA championship including venue details, events, results, competitors, and championship-specific information like regional significance.

Args: championship_id: Championship ID (e.g., "WC2023" for World Championship 2023, "Euro2022" for European Championship 2022)

Returns: Detailed championship information including all competition data plus championship-specific details

Example: get_championship_details("WC2023") - World Championship 2023 details

Inputs: championship_id (required). Returns: object

get_competition_by_idA

Get detailed information about a specific competition by its ID.

Returns comprehensive information about a WCA competition including venue details, events, results, and organizer information.

Args: competition_id: WCA competition ID (e.g., "WC2023")

Returns: Detailed competition information

Inputs: competition_id (required). Returns: object

get_competition_event_resultsA

Get results for a specific event within a WCA competition.

Returns focused results data for a single event in a competition. By default, returns only Final round results for better LLM processing.

Args: competition_id: WCA competition ID (e.g., "WC2025", "CubingUSANationals2024") event_id: WCA event ID (e.g., "333" for 3x3x3 Cube, "222" for 2x2x2, "333bf" for 3x3x3 Blindfolded, "444" for 4x4x4) round: Specific round to filter by (default: "Final"). Use "all" for all rounds, or specify: "Final", "Semi Final", "Second round", "First round" limit: Maximum number of results to return (optional) include_solves: Whether to include detailed solve times (default: False)

Returns: Filtered results data including: - Competitor performances for the specified round - Position, best single, and average times - Optionally detailed solve breakdowns

Example: get_competition_event_results("WC2025", "333") - Final round only (16 results) get_competition_event_results("WC2025", "333", round="all") - All rounds (2490 results) get_competition_event_results("WC2025", "333", limit=10) - Top 10 from Final

Inputs: competition_id (required), event_id (required), round, limit, +1 more. Returns: object

get_competition_resultsA

Get all results for a WCA competition.

Returns comprehensive results data for all events in a competition, including competitor performances, solve breakdowns, round information, and final rankings. This provides complete competition outcome data.

Args: competition_id: WCA competition ID (e.g., "WC2023", "CubingUSANationals2024")

Returns: Complete results data for all events in the competition including: - Individual solve times and averages - Round-by-round progression - Final rankings and positions - DNF/DNS information - Competitor details

Example: get_competition_results("WC2023") - All results from World Championship 2023

Inputs: competition_id (required). Returns: object

get_person_by_wca_idA

Get detailed information about a specific WCA competitor by their WCA ID.

Returns information about a speedcuber with configurable detail levels. By default, returns basic info, personal records, rankings, and medals without the verbose competition results that can make responses extremely long.

Args: wca_id: WCA ID of the person (e.g., "2003SEAR02") competition_id: Optional competition ID to get results from a specific competition (e.g., "WC2023") include_competition_results: Include detailed competition results (default: False) include_personal_records: Include personal best records (default: True) include_rankings: Include current world/continental/national rankings (default: True) include_medals: Include medal counts (default: True) max_recent_competitions: If including results, limit to N most recent competitions (default: 5)

Returns: Filtered person information based on the specified parameters

Inputs: wca_id (required), competition_id, include_competition_results, include_personal_records, +3 more. Returns: object

get_rankingsA

Get current world rankings and records for a specific event.

Returns the current rankings for any WCA event, which includes world records and top performers. Can filter by region (world, continent, or country).

Args: event_id: WCA event ID (e.g., "333" for 3x3x3 Cube, "222" for 2x2x2) region: Region code - "world" for world rankings, continent codes like "Europe", or country ISO2 codes like "US", "CN" (default: "world") ranking_type: Type of ranking - "single" for single solve records or "average" for average records (default: "single") page: Page number (1-based, default: 1) per_page: Items per page (max 100, default: 25)

Returns: Paginated ranking data with current records and top performers

Inputs: event_id (required), region, ranking_type, page, +1 more. Returns: object

get_wca_continentsA

Get all WCA continents.

Returns a list of all continents recognized by the World Cube Association including continent names and identifiers used for regional filtering.

Returns: List of WCA continents with names and identifiers

Inputs: no named parameters. Returns: result

get_wca_countriesA

Get all WCA countries.

Returns a list of all countries recognized by the World Cube Association including country names and ISO2 codes used for regional filtering.

Returns: List of WCA countries with names and ISO2 codes

Inputs: no named parameters. Returns: result

get_wca_eventsA

Get all official WCA events.

Returns a list of all official World Cube Association events including event IDs, names, and formats.

Returns: List of WCA events with their details

Inputs: no named parameters. Returns: result

search_championshipsA

Search for WCA championships with optional filtering.

Returns championship competitions which are the most prestigious competitions in speedcubing including World Championships, Continental Championships, and National Championships.

Args: page: Page number for pagination (default: 1) championship_type: Filter by championship type: - "world" for World Championships - continent codes like "Europe", "Asia", "North America" for Continental Championships
- country ISO2 codes like "US", "CN", "DE" for National Championships - None for all championships (default)

Returns: Paginated championship data with competition details

Example: search_championships(championship_type="world") - World Championships only search_championships(championship_type="US") - US National Championships

Inputs: page, championship_type. Returns: object

search_competitions_by_dateA

Search for WCA competitions on a specific date.

Returns a small, focused list of competitions that occurred on the exact date specified. This typically returns 1-5 competitions, making it perfect for LLM processing.

Args: year: Year (e.g., 2023, 2024) month: Month (1-12) day: Day (1-31)

Returns: Competition data for the specific date (typically 1-5 competitions)

Example: search_competitions_by_date(year=2024, month=3, day=15) - Competitions on March 15, 2024

Inputs: year (required), month (required), day (required). Returns: object

search_competitions_by_eventA

Search for WCA competitions that include a specific event.

Returns competitions that feature the specified WCA event. Results are paginated to manage the response size.

Args: event_id: WCA event ID (e.g., "333" for 3x3x3 Cube, "222" for 2x2x2, "333bf" for 3x3x3 Blindfolded) page: Page number for pagination (default: 1)

Returns: Paginated competition data for competitions featuring the specified event

Example: search_competitions_by_event(event_id="333bf") - Competitions with 3x3x3 Blindfolded

Inputs: event_id (required), page. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 12 tools

    Disambiguation4/5

    Most tools have distinct purposes, but there is some overlap between get_championship_details and get_competition_by_id, as championships are a subset of competitions, which could cause confusion. Additionally, get_competition_results and get_competition_event_results serve similar functions but at different granularities, though their descriptions clarify the scope. Overall, the tools are mostly distinguishable with minor ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with snake_case, such as get_championship_details, search_competitions_by_date, and get_wca_events. The naming is predictable and uniform across all 12 tools, making it easy for an agent to understand and use them without confusion.

    Tool Count5/5

    With 12 tools, the server is well-scoped for its domain of WCA (World Cube Association) data access. The tools cover key areas like competitions, championships, persons, rankings, and metadata, each serving a clear purpose without being excessive or insufficient. This count aligns well with the complexity of the domain.

    Completeness4/5

    The tool set provides comprehensive coverage for querying WCA data, including competitions, championships, persons, rankings, and events. However, there are minor gaps, such as no tools for updating or deleting data (which may be intentional if read-only) and limited filtering options beyond basic searches. Overall, it supports most agent workflows effectively with slight room for enhancement.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to query CTF (Capture The Flag) cybersecurity competition data from CTFtime.org, including events, team rankings, results, and votes through the public CTFtime API.
      7
      38 npm
      MIT
    • 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
    • F
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to access and analyze intervals.icu training data including activities, fitness metrics (CTL/ATL/TSB), wellness stats, and calendar events. Supports natural language querying of athletic performance for training insights and workout planning.
      6
      -
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to query speedrun.com for games, categories, leaderboards, world records, players, and personal bests using natural language.
      16
      44 PyPI
      MIT