YOKATLAS API MCP Sunucusu

YOKATLAS MCP：トルコ高等教育アトラス用 MCP サーバー

このプロジェクトでは、YÖKATLAS のデータに簡単にアクセスできる FastMCP サーバーを作成します。これにより、YÖKATLAS から学士課程および準学士課程のプログラムを検索し、詳細な統計情報を取得する機能を、Model Context Protocol (MCP) に対応した LLM（大規模言語モデル）アプリケーション（Claude Desktop や 5ire など）やその他のクライアントでツールとして利用できるようになります。

🎯 主な機能

• YÖKATLAS の選好ガイド JSON API にプログラムからアクセスするための標準 MCP インターフェース。
• 次の機能を利用できます。
  • 統合スマート検索： 学士課程と準学士課程をまとめて検索し、ファジーマッチングで大学名、プログラム名、県名を特定します（例：「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 は 5ire など、Claude Desktop 以外の MCP クライアントにも対応しています。

⚠️ v0.6.0 の破壊的変更 — YÖK Atlas は 2026 年 4 月に React ベースの SPA に移行し、従来の HTML スクレイピング用エンドポイントと詳細なアトラスデータ（性別／高校分野別の分布、教員の職位別分布、年度別 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 session を開き、エディターのサイドパネルにある 「…」 ドロップダウンメニューをクリックします
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 — 1 つのプログラムに絞り込みます（旧「atlas details」ユースケース向け）。
    • min_basari_sirasi、max_basari_sirasi：合格順位の範囲。
    • page、size、sort_by、direction：ページネーションと並べ替え（デフォルト：basariSirasi ASC、size=20、sizeの最大値は500）。
  • 返されるデータ： 各検索結果には、4 年分の統計（current＋history）が含まれます。定員、入学者数、最低点、合格順位、KPSS スコア、教員数が含まれます。

• search_netler：Net Wizard — 最後に入学した人の科目別正答数。

  • パラメーター：
    • 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ファイルをご覧ください。