smarthr-member-mcp-tools

SmartHR を 従業員として 使っている人向けの MCP サーバーです。 自分の給与明細・賞与明細をまとめて取得し、年末調整で入力する「給与の収入金額（見込額）」を計算します。

• 管理者用の公式 API トークンは使いません。自分のアカウントでログインしたブラウザ（手元の Google Chrome）を Playwright で操作します。

• SmartHR 社の公式ツールではありません。画面構成が変わると動かなくなることがあります。

• 計算結果は見込額です。最終的な申告内容はご自身で確認してください。

できること

estimate_income の計算方法:

• 給与の収入金額 = 課税対象額 + 社会保険合計。立替精算や通勤手当などの非課税分を除くためです。これらの行がない明細では 支給 合計 を使います。

• 発行済みの明細は実額を使います。

• 最後の給与明細より後の月は、最新の給与明細の額で推計します（昇給を反映）。

• まだ支給されていない賞与は、前年同月の賞与の額で推計します。

• 推計分は rows の中で estimated: true になっています。賞与額の変更などが分かっている場合は、それをもとに補正してください。

Related MCP server: JP Invoice & Tax MCP

セットアップ

uv と Google Chrome が必要です。

git clone https://github.com/tunagohan/smarthr-member-mcp-tools.git
cd smarthr-member-mcp-tools
uv sync

Claude Code

claude mcp add smarthr-member \
  -e SMARTHR_URL=https://<your-tenant>.smarthr.jp \
  -- uv run --directory /path/to/smarthr-member-mcp-tools smarthr-member-mcp

Claude Desktop など

{
  "mcpServers": {
    "smarthr-member": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/smarthr-member-mcp-tools", "smarthr-member-mcp"],
      "env": { "SMARTHR_URL": "https://<your-tenant>.smarthr.jp" }
    }
  }
}

使い方

「今年の給与収入の見込額を出して」のように頼んでください。

初回やログインが切れているときは Chrome が開きます。5 分以内にログインすると、そのまま取得を続けます（SSO や 2 段階認証もそのまま使えます）。

データの扱い

• ログイン状態は ~/.smarthr-member-mcp/profile に保存されます（SMARTHR_PROFILE_DIR で変更可）。このリポジトリの中には保存されません。

• 取得した明細は MCP サーバーのメモリ上にだけ保持し、ファイルには書き出しません。

• 明細の内容は、MCP クライアント（AI アシスタント）に送られます。

画面構成が変わって動かなくなったとき

数字を伏せた状態で画面の構造を出力するスクリプトがあります。

SMARTHR_URL=https://<your-tenant>.smarthr.jp uv run smarthr-member-recon

出力先は recon-output/recon.json です（git の管理外）。氏名や会社名がページ本文に残るので、共有する前に中身を確認してください。

開発

uv run pytest

License

MIT