Skip to main content
Glama
tcs_mcp_claude
by exthnet

tcs_mcp_claude

九州大学スーパーコンピュータ玄界の TCS(Fujitsu PRIMEHPC JobScheduler / PJM)を Claude から操作するための Model Context Protocol (MCP) サーバー。

Claude Code と統合することで、ジョブの投入・状態確認・削除・リソース照会・出力ファイルの読み取りを自然言語で行えるようになる。


提供ツール

ツール

対応コマンド

説明

submit_job

pjsub

ジョブスクリプトを投入してジョブ ID を返す

list_jobs

pjstat

実行中・キュー待ちジョブの一覧(履歴も取得可)

get_job_status

pjstat <id>

特定ジョブの状態確認

delete_job

pjdel

ジョブの削除・キャンセル

get_resource_groups

pjstat --rsc

利用可能なリソースグループの一覧

get_quota_limits

pjstat --limit

クォータ・上限値の確認

generate_job_template

—

Genkai 向けジョブスクリプトのテンプレート生成

list_resource_groups

—

Genkai の既知リソースグループ一覧

list_files

—

作業ディレクトリのファイル一覧

read_file

—

テキストファイルの内容を読み取り

read_job_output

—

ジョブの標準出力・エラーファイルを読み取り


Related MCP server: clausius

利用形態

シナリオ A(推奨): 玄界のログインノード上で Claude Code を直接実行

[玄界ログインノード]
  Claude Code → tcs-mcp (stdio) → pjsub/pjstat/pjdel

シナリオ B: ローカル PC から SSH 経由でサーバープロセスを玄界で動かす

[ローカル PC]               [玄界ログインノード]
  Claude Code → SSH トンネル → tcs-mcp (stdio) → pjsub/pjstat/pjdel

シナリオ C: ローカル PC に MCP サーバーを置き、SSH で玄界へ接続

[ローカル PC]
  Claude Code → tcs-mcp (SSH モード) → SSH → pjsub/pjstat/pjdel [玄界]

インストール

前提条件

  • Python 3.11 以上(玄界では miniforge3 を推奨)

  • 玄界アカウントと PJM コマンド(/usr/local/bin/pjsub 等)へのアクセス

手順(玄界ログインノード上)

# miniforge 環境をアクティベート
source ~/miniforge3/bin/activate

# このリポジトリをクローン
git clone git@github.com:exthnet/tcs_mcp_claude.git
cd tcs_mcp_claude

# パッケージをインストール(開発モード)
pip install -e .

# インストール確認
tcs-mcp --help

Claude Code への登録

シナリオ A / B(玄界上で tcs-mcp を動かす場合)

プロジェクトルートの .mcp.json がそのまま使えます(Claude Code を tcs_mcp_claude/ ディレクトリで起動した場合に自動読み込み)。

{
  "mcpServers": {
    "tcs": {
      "type": "stdio",
      "command": "/home/pj24001603/ku40000105/miniforge3/bin/tcs-mcp",
      "env": {
        "TCS_MODE": "local",
        "TCS_WORK_DIR": "/home/pj24001603/ku40000105/work"
      }
    }
  }
}

別のディレクトリで Claude Code を使う場合は、~/.claude/ 以下に .mcp.json を置くか、claude mcp add コマンドで追加してください。

シナリオ B(ローカル PC から SSH トンネル経由)

ローカル PC の .mcp.json または Claude Code の MCP 設定に追加:

{
  "mcpServers": {
    "tcs": {
      "type": "stdio",
      "command": "ssh",
      "args": [
        "-i", "~/.ssh/id_rsa_genkai",
        "ku40000105@genkai.cc.kyushu-u.ac.jp",
        "/home/pj24001603/ku40000105/miniforge3/bin/tcs-mcp"
      ]
    }
  }
}

シナリオ C(ローカル PC に MCP サーバーをインストール、SSH で玄界へ)

ローカル PC にもパッケージをインストールし、SSH モードで起動:

{
  "mcpServers": {
    "tcs": {
      "type": "stdio",
      "command": "tcs-mcp",
      "env": {
        "TCS_MODE": "ssh",
        "TCS_SSH_HOST": "genkai.cc.kyushu-u.ac.jp",
        "TCS_SSH_USER": "ku40000105",
        "TCS_SSH_KEY_FILE": "~/.ssh/id_rsa_genkai"
      }
    }
  }
}

設定

環境変数または .env ファイル(.env.example を参照)で設定します。

変数

デフォルト

説明

TCS_MODE

local

実行モード: local または ssh

TCS_WORK_DIR

~/work

ジョブ出力ファイルを探す作業ディレクトリ

TCS_SSH_HOST

genkai.cc.kyushu-u.ac.jp

SSH ホスト名(ssh モード時)

TCS_SSH_USER

—

SSH ユーザ名(ssh モード時、必須)

TCS_SSH_KEY_FILE

~/.ssh/id_rsa

SSH 秘密鍵パス

TCS_PJSUB_PATH

/usr/local/bin/pjsub

pjsub の絶対パス

TCS_PJSTAT_PATH

/usr/local/bin/pjstat

pjstat の絶対パス

TCS_PJDEL_PATH

/usr/local/bin/pjdel

pjdel の絶対パス

TCS_LOG_LEVEL

INFO

ログレベル


使用例(Claude との会話)

あなた: 現在のジョブ一覧を見せて

Claude: [list_jobs を呼び出し]
        現在実行中のジョブはありません。

あなた: a-batch-low で4コア、30分のジョブを投入したい

Claude: [generate_job_template を呼び出し]
        以下のスクリプトを生成しました:
        #!/bin/bash
        #PJM -N myjob
        #PJM -L rscgrp=a-batch-low
        #PJM -L vnode-core=4
        #PJM -L elapse=00:30:00
        ...

        投入しますか?

あなた: 投入して

Claude: [submit_job を呼び出し]
        ジョブ ID 6401234 で投入しました。

開発

テストの実行

source ~/miniforge3/bin/activate
pip install -e ".[dev]"
pytest tests/ -v

テストは tests/fixtures/ に保存した実際の pjstat 出力を使用するため、玄界への接続不要で実行できます。

プロジェクト構造

src/tcs_mcp/
├── __main__.py       # エントリポイント
├── server.py         # MCPServer の構築・ツール登録
├── config.py         # TCSConfig (pydantic-settings)
├── executor.py       # LocalExecutor / SSHExecutor
├── parsers.py        # pjstat 出力パーサ
└── tools/
    ├── jobs.py           # submit_job, list_jobs, get_job_status, delete_job
    ├── resources.py      # get_resource_groups, get_quota_limits
    ├── files.py          # list_files, read_file, read_job_output
    ├── templates.py      # ジョブスクリプトテンプレートロジック
    └── templates_tool.py # generate_job_template, list_resource_groups (MCP ツール)

対応リソースグループ(Genkai)

グループ

種別

用途

a-batch-low / a-batch

CPU

バッチジョブ(Xeon Platinum 8490H)

a-inter-low / a-inter

CPU

インタラクティブジョブ

b-batch-low / b-batch

GPU

GPU バッチジョブ(NVIDIA A100)

b-batch-mig-low / b-batch-mig

GPU (MIG)

MIG パーティション GPU ジョブ

b-inter-low / b-inter

GPU

GPU インタラクティブジョブ

c-batch-low / c-batch

CPU

その他バッチ


注意事項

  • pjmod は玄界に存在しないため非対応

  • ファイル操作ツール(read_file, list_files)は TCS_WORK_DIR 配下のみアクセス可(パストラバーサル防止)

  • MCP バージョン 2.0.0 を使用(mcp.server.mcpserver.MCPServer)

Available Tools

11 tools
delete_jobC

Delete (cancel) a queued or running job.

Returns: {"success": bool, "job_id": str, "message": str}

Inputs: job_id (required). Returns: object

generate_job_templateA

Generate a PJM job script template for Genkai.

Available rscgrps: a-batch-low, a-batch, b-batch-low, b-batch, b-batch-mig-low, b-batch-mig, c-batch-low, c-batch, and their -inter variants.

Returns a shell script string with #PJM directives ready to submit with pjsub.

Inputs: gpu, cores, elapse, rscgrp, +4 more. Returns: result

get_job_statusA

Get status of a specific job by ID.

Returns list of job dicts (same format as list_jobs). Raises RuntimeError if the job is not found.

Inputs: job_id (required). Returns: result

get_quota_limitsC

Get quota and limit information for the current user.

Returns a dict with sections: USER, GROUP, ALL. Each section contains a list of {limit_name, limit, alloc} dicts.

Inputs: rscgrp. Returns: object

get_resource_groupsA

List available resource groups and their sizes on Genkai.

rscgrp: filter by specific resource group name. Returns list of dicts with keys: rscunit, rscunit_size, rscgrp, rscgrp_size.

Inputs: rscgrp. Returns: result

list_filesA

List files in a work directory.

directory: path to list (defaults to work_dir). pattern: glob pattern to filter filenames. Returns list of {path, name, is_dir} dicts.

Inputs: pattern, directory, max_entries. Returns: result

list_jobsA

List jobs for the current user.

history_days: include completed jobs from the past N days (max 90). rscgrp: filter by resource group name. Returns list of job dicts with keys: job_id, job_name, md, st, user, start_date, elapse_lim, node_require, vnode, core, v_mem.

Inputs: rscgrp, history_days. Returns: result

list_resource_groupsB

List all known Genkai resource groups and their type (cpu/gpu/gpu_mig).

Inputs: no named parameters. Returns: result

read_fileA

Read a text file from the Genkai filesystem.

Only files within work_dir are accessible. Returns {content, truncated, size_bytes}.

Inputs: file_path (required), max_bytes. Returns: object

read_job_outputA

Read the stdout or stderr output file of a completed job.

Searches for output files by common PJM naming patterns: <job_name><job_id>.out / .err STDIN<job_id>.out / .err

Returns {content, truncated, path}.

Inputs: job_id (required), job_name, work_dir, file_type, +1 more. Returns: object

submit_jobA

Submit a batch job to the TCS/PJM scheduler on Genkai.

Provide the full job script content. Resource directives in the script take precedence over the parameters here. The parameters are ignored when the script already contains #PJM directives.

Returns: {"job_id": str, "message": str}

Inputs: script_content (required), gpu, cores, elapse, +4 more. Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 11 tools

    Disambiguation4/5

    Most tools have distinct purposes: file operations, job lifecycle, and resource queries are clearly separated. However, list_resource_groups and get_resource_groups both list resource groups but with differing details, which could cause misselection.

    Naming Consistency4/5

    Tool names generally follow a consistent verb_noun pattern in snake_case, such as list_files, submit_job, delete_job. The overlap between list_resource_groups and get_resource_groups introduces slight inconsistency, but the overall pattern is predictable.

    Tool Count5/5

    Eleven tools is well within the ideal range for a domain-specific server covering file access and job management. Each tool serves a clear purpose without unnecessary bloat.

    Completeness5/5

    The surface covers the full job lifecycle: template generation, submission, listing, status check, output retrieval, and deletion. Additionally, resource group and quota queries address administrative needs. No obvious dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      C
      maintenance
      An MCP server that enables LLMs to execute Python code on GPU-accelerated compute nodes within SLURM-managed HPC environments. It bridges local clients to remote clusters by launching JupyterLab sessions via SLURM jobs to facilitate high-performance notebook-based computation.
      7
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      An MCP server for monitoring and managing multi-cluster Slurm GPU jobs, enabling AI agents to execute commands, check allocations, and explore logs across HPC clusters.
      1
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for the Fugaku supercomputer that enables natural language job submission, monitoring, file transfer, and command execution via AI agents like Claude Code.
      5
      MIT