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

一个用于获取世界魔方协会 (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 可执行文件路径，使其与你环境中的

📄 许可证

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