jp-school-code-mcp

文部科学省が公表する学校コードを、学校名や都道府県、学校種、設置区分から調べられます。コードが分かっていれば、所在地などを照会し、2つの公表版で同じ学校の記録を比較できます。

利用前に

uv と Git が必要です。Python 3.12以上に対応しています。APIキーの設定は不要です。

Related MCP server: Japan Area Code MCP Server

MCPクライアントに登録する

公開GitHubリポジトリから uvx で起動します。初回は依存関係の準備に時間がかかることがあります。

Codex

codex mcp add jp-school-code-mcp -- uvx --python 3.12 --from git+https://github.com/koizumikento/jp-school-code-mcp.git@main jp-school-code-mcp
codex mcp list

codex mcp list で登録を確認し、Codexの新しいセッションで /mcp を開くと、接続状態を確認できます。Codexの公式設定ガイド

Codexのデスクトップアプリでは、設定の「MCP servers」でSTDIOサーバーを追加し、下のJSON例と同じコマンド・引数を指定する方法もあります。

Claude Desktop / Cursor

次のファイルに設定します。

• Claude Desktop（Windows） %APPDATA%/Claude/claude_desktop_config.json

• Claude Desktop（macOS） ~/Library/Application Support/Claude/claude_desktop_config.json

• Cursor .cursor/mcp.json（プロジェクト内）

既に mcpServers がある場合は、その中にサーバーの項目を追加してください。保存後にクライアントを再起動し、ツールが表示されるか確認します。設定ファイルの場所と接続手順

{
  "mcpServers": {
    "jp-school-code-mcp": {
      "command": "uvx",
      "args": [
        "--python",
        "3.12",
        "--from",
        "git+https://github.com/koizumikento/jp-school-code-mcp.git@main",
        "jp-school-code-mcp"
      ]
    }
  }
}

uvx が見つからない場合は、設定のコマンドに実行ファイルの絶対パスを指定してください。

登録後は、チャットで次のように聞けます。

東京都の東京大学を探して、学校コードとデータの基準日を教えて。

MCPツール

学校種には B1（小学校）、C1（中学校）、D1（高等学校）、F1（大学）などがあります。設置区分 operator_category は 1（国立）、2（公立）、3（私立）です。学校コードの構成とコード表（PDF）

公表版の日付には、配布ページに載っている基準日を YYYY-MM-DD で指定します。片方の版にコードが見つからない場合、その版の school と比較結果の changed_fields は null になります。コードが変更された場合は、新旧のコードをそれぞれ照会してください。

CLIで使う

結果は標準出力にUTF-8のJSONで返ります。

uvx --python 3.12 --from git+https://github.com/koizumikento/jp-school-code-mcp.git@main jp-school-code-mcp search-schools --name "東京大学" --prefecture "東京都" --school-type F1 --operator-category 1
uvx --python 3.12 --from git+https://github.com/koizumikento/jp-school-code-mcp.git@main jp-school-code-mcp compare-school-records --school-code F113310103073 --from-date 2025-05-01 --to-date 2026-05-01

Pythonから呼び出す

リポジトリをクローンし、依存関係を準備します。

git clone https://github.com/koizumikento/jp-school-code-mcp.git
cd jp-school-code-mcp
uv sync --locked

次の例を example.py に保存し、クローン先で uv run --locked python example.py を実行します。

import asyncio
from datetime import date

from jp_school_code_mcp import compare_school_records, search_schools

print(asyncio.run(search_schools(prefecture="東京都", school_type="F1", operator_category="1")))
print(asyncio.run(compare_school_records("F113310103073", date(2025, 5, 1), date(2026, 5, 1))))

データの更新

MCP・CLI・Pythonは同じローカルキャッシュを使います。最新版と、基準日を指定した公表版は別々に保存します。初回は版ごとに複数の公式CSVを取得するため、時間がかかることがあります。MCPクライアントでタイムアウトする場合は、使いたい版をCLIで先に照会してキャッシュを作成してください。確認間隔は7日で、期限を過ぎた最初の照会時に更新を確認します。更新に失敗した場合は直前の正常な版を返し、cache.refresh_failed と cache.checked_at で失敗の有無と最後に確認できた日時を判別できます。初回取得に失敗した場合はエラーになります。

最新版をすぐに更新したいときは次を実行します。

uvx --python 3.12 --from git+https://github.com/koizumikento/jp-school-code-mcp.git@main jp-school-code-mcp refresh

キャッシュはWindowsでは %LOCALAPPDATA%/jp-school-code-mcp、その他では $XDG_CACHE_HOME/jp-school-code-mcp または ~/.cache/jp-school-code-mcp に保存されます。JP_SCHOOL_CODE_CACHE_DIR で保存先を指定できます。

データの出典と利用条件

結果には公表版の基準日と暫定・確定の区分が付きます。利用する際は文部科学省の出典を示し、加工した場合はその旨を明記してください。学校コードの配布ページ・文部科学省ウェブサイト利用規約

MIT Licenseはこのリポジトリのコードに適用します。