YOKATLAS API MCP Sunucusu

YOKATLAS MCP：土耳其高等教育 Atlas 的 MCP 服务

本项目创建了一个 FastMCP 服务，方便访问 YÖKATLAS 数据。这样一来，搜索 YÖKATLAS 中的本科和专科项目、获取详细统计数据等操作，就可以作为工具供支持 Model Context Protocol (MCP) 的 LLM（大模型）应用（例如 Claude Desktop 或 5ire）及其他客户端使用。

🎯 主要功能

• 提供标准 MCP 接口，以编程方式访问 YÖKATLAS 志愿填报指南 JSON API。
• 具备以下功能：
  • 统一智能搜索： 本科 + 专科统一搜索；通过模糊匹配解析大学、项目和省份名称（例如：“boğaziçi” → “BOĞAZİÇİ ÜNİVERSİTESİ”）
  • 4 年统计数据： 一次性获取每个项目的招生名额、录取人数、最低分、排名、学术人员和 KPSS 数据（当前 + 3 年历史数据）
  • 分数计算助手： 最后一位录取者各科净得分（TYT/AYT/YDT）、最低分、OBP 和系数
  • 查询工具： 直接获取大学、项目组和省份列表
  • 筛选： 分数类型（SAY/SÖZ/EA/DİL/TYT）、大学类型（DEVLET/VAKIF）、排名范围、分页和排序
• 可通过 Claude Desktop 应用搭配 fastmcp install 命令（或手动配置）轻松集成。
• YOKATLAS MCP 也支持 Claude Desktop 之外的 MCP 客户端，例如 5ire。

⚠️ v0.6.0 重大变更 — YÖK Atlas 于 2026 年 4 月迁移到基于 React 的 SPA，旧版 HTML 抓取端点和详细 Atlas 数据（性别/高中领域分布、学术人员职称分布、按年份划分的 KPSS 数据等）已从整个网站移除。此 MCP 针对新的 JSON API 编写；只会返回官方 API 提供的基本统计数据。

---

🚀 5 分钟快速开始（远程 MCP）

✅ 无需安装！立即使用！

🔗 远程 MCP 地址： https://yokatlasmcp.fastmcp.app/mcp

在 Claude Desktop 中使用

1. 打开 Claude Desktop
2. Settings → Connectors → Add Custom Connector
3. 填写信息：
   • Name： YOKATLAS MCP
   • URL： https://yokatlasmcp.fastmcp.app/mcp
4. 点击 Add 按钮
5. 立即开始使用！ 🎉

在 Google Antigravity 中使用

1. 打开 Agent 会话，点击编辑器侧边栏中的 “…” 下拉菜单
2. 选择 MCP Servers 选项——此时会打开 MCP Store
3. 点击顶部的 Manage MCP Servers 按钮
4. 点击 View raw config 选项
5. 将以下配置添加到 mcp_config.json 文件中：

{
  "mcpServers": {
    "yokatlas-mcp": {
      "serverUrl": "https://yokatlasmcp.fastmcp.app/mcp/",
      "headers": {
        "Content-Type": "application/json"
      }
    }
  }
}

💡 提示： 使用远程 MCP，无需安装 Python、uv 或任何其他内容，即可直接通过 Claude Desktop 访问 YÖKATLAS 数据！

---

🚀 轻松安装，以便与 Claude 以外的模型搭配使用（示例：5ire）

本部分适用于希望将 YOKATLAS MCP 工具与 5ire 等 Claude Desktop 以外的 MCP 客户端搭配使用的用户。

• 安装 Python： 系统中必须安装 Python 3.12。安装时，请务必勾选“Add Python to PATH”（将 Python 添加到 PATH）选项。可从此处下载。

• 安装 Git（Windows）： 在计算机上下载并安装 git 软件。请下载“Git for Windows/x64 Setup”选项。

• 安装 uv：

  • Windows 用户（PowerShell）： 打开一个 CMD 窗口并运行此代码：powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  • Mac/Linux 用户（终端）： 打开一个终端窗口并运行此代码：curl -LsSf https://astral.sh/uv/install.sh | sh

• Microsoft Visual C++ Redistributable（Windows）： 某些 Python 软件包需要它才能正常运行。请从此处下载并安装。

• 下载并安装适用于您操作系统的 5ire MCP 客户端。

• 打开 5ire。从 Workspace -> Providers 菜单中输入您要使用的 LLM 服务的 API 密钥。

• 进入 Tools 菜单。点击标有 +Local 或 New 的按钮。

  • Tool Key： yokatlasmcp
  • Name： YOKATLAS MCP
  • Command：

    uvx --from git+https://github.com/saidsurucu/yokatlas-mcp yokatlas-mcp
    

  • 点击 Save 按钮保存。

• 现在，您应该可以在 Tools 下看到 YOKATLAS MCP。将鼠标悬停在其上方，点击右侧出现的按钮以启用它（指示灯应亮起绿色）。

• 现在，您可以与 YOKATLAS MCP 对话了。

---

⚙️ 手动安装 Claude Desktop

1. 前置要求： 确保系统中已安装 Python、uv 和（Windows 上的）Microsoft Visual C++ Redistributable。详情请参阅上方“安装 5ire”部分的相关步骤。

2. Claude Desktop Settings -> Developer -> Edit Config。

3. 在打开的 claude_desktop_config.json 文件中，将以下内容添加到 mcpServers 下：

   {
     "mcpServers": {
       "YOKATLAS MCP": {
         "command": "uvx",
         "args": [
           "--from", "git+https://github.com/saidsurucu/yokatlas-mcp",
           "yokatlas-mcp"
         ]
       }
     }
   }
   

4. 关闭并重新启动 Claude Desktop。

---

🛠️ 可用工具（MCP Tools）

此 FastMCP 服务为 LLM 模型提供以下工具：

🔍 搜索

• search_programs：本科 + 专科联合搜索（智能模糊匹配）。

  • 参数：
    • degree_type：'bachelor'（本科）或 'associate'（专科）。留空时返回两者。
    • puan_turu：SAY、SÖZ/SOZ、EA、DİL/DIL、TYT（会自动规范化 ASCII 变体）。
    • universite、program、il：智能模糊匹配（例如 "boğaziçi"、"bilgisayar"、"ankara"）。
    • universite_turu：DEVLET 或 VAKIF。
    • kilavuz_kodu：int — 筛选单个专业（用于旧版“atlas 详情”场景）。
    • min_basari_sirasi、max_basari_sirasi：录取排名范围。
    • page、size、sort_by、direction：分页和排序（默认：basariSirasi ASC，size=20，最大 size=500）。
  • 返回数据： 每条结果包含 4 年统计数据（current + history）：招生名额、录取人数、最低分、录取排名、KPSS 分数、学术人员数量。

• search_netler：Net Sihirbazı（净分向导）— 最后一位录取者各科目的答对净题数。

  • 参数：
    • universite、program：智能模糊匹配（单个值，不是列表）。解析出 program 后，若未明确指定 puan_turu，则会根据匹配的专业组自动填充。
    • puan_turu：SAY、SÖZ/SOZ、EA、DİL/DIL、TYT。
    • universite_turu：DEVLET 或 VAKIF。
    • yil：筛选特定年份（例如 2024）。
    • katsayi：按分数计算中使用的系数筛选。
    • page、size：分页（默认：size=20，最大 size=500）。
  • 返回数据： 根据 puan_turu 而异的净分字段（始终包含 TYT；SAY/SÖZ/EA/DİL 会添加各自的 AYT/YDT 字段），以及 katsayi、taban_puan、obp。

📚 查询工具

• list_universities：列出 YÖKATLAS 中的所有大学（universite_id、universite_adi）。
• list_program_groups：列出所有专业组（birim_grup_id、birim_grup_adi、puan_turu）— 用于查找有效的 program 筛选值。
• list_cities：列出 81 个省（il_kodu、il_adi）。

🔄 v0.5 → v0.6 迁移

旧版 API 用户可参考以下简要说明：

旧版（v0.5）	新版（v0.6）
search_bachelor_degree_programs	search_programs(degree_type='bachelor', ...)
search_associate_degree_programs	search_programs(degree_type='associate', ...)
get_bachelor_degree_atlas_details(yop_kodu, year)	search_programs(kilavuz_kodu=N)（搜索结果中包含 4 年数据）
get_associate_degree_atlas_details(yop_kodu, year)	search_programs(kilavuz_kodu=N)
score_type	puan_turu（新增 TYT）
fee_type / education_type / availability	已移除（新 API 中没有直接对应项）
yop_kodu (str)	kilavuz_kodu (int)

---

📜 许可证

本项目采用 MIT 许可证授权。详情请参阅 LICENSE 文件。