SmartHR従業員データをClaudeで確認・更新する人事効率化

SmartHR MCPサーバーを繋ぐと、Claudeに「入社した田中さんを登録して招待メールを送って」のような指示を渡せるようになります。ただし登録も検索も、ツールの引数は名前でなくIDや固定の項目で受ける作りです。依頼文をそのまま渡すだけでは通らない箇所があります。

この記事は、公開されているサーバーの実装(server.py・smarthr_client.py)を読み、入退社・異動・検索・家族情報の4場面で何が任せられ、どこで手が止まるかを確認したものです。

接続する前に知っておくこと

サーバーはTomoyaGoto/smarthr_mcp_serverという個人リポジトリの実装です。MITライセンスで、READMEの免責事項には「利用して行う一切の行為、被った損害・損失に対しては、一切の責任を負いかねます」とあります。SmartHRが提供する公式サーバーではありません。

READMEの導入手順はClaude for Desktopが対象で、smarthr_mcp_server.jsonの内容を設定ファイルに追記してClaudeを再起動する流れです。Claude Codeの手順は載っていません。Claude Codeでは、標準入出力で動くサーバーとしてclaude mcp addで登録します。手元のv2.1.285でclaude mcp add --helpを確認すると、環境変数は-e、起動コマンドは--の後ろに書く形式でした。

git clone https://github.com/TomoyaGoto/smarthr_mcp_server
claude mcp add smarthr \
  -e SMARTHR_API_BASE_URL="https://your-subdomain.smarthr.jp/api" \
  -e SMARTHR_API_KEY="your-api-token" \
  -- uv --directory /path/to/smarthr_mcp_server run python main.py

main.pyの起動コマンドは、リポジトリ付属のsmarthr_mcp_server.jsonにあるuv --directory ... run python main.pyと同じです。上のコマンドはその起動コマンドをclaude mcp addの形に置き直したもので、実際のSmartHRテナントへの接続は試していません。

ベースURLはリポジトリ内で書き方が食い違っています。READMEの.env例はhttps://app.smarthr.jp/api、.env_sampleはhttps://{your_subdomain}.smarthr.jp/apiで、各テナントのサブドメインを指定する説明が付いています。接続先は自社のサブドメインで指定します。

入社登録から招待メールまで

新入社員の登録はsmarthr_create_crew()、招待メールはsmarthr_invite_crew()の2つで完結します。ただし「営業部・正社員で登録して」がそのまま通るわけではありません。

smarthr_create_crew()の引数は1人分の情報をまとめた辞書で、部署はdepartment_ids、雇用形態はemployment_type_idと、どちらもIDで指定します。雇用形態には旧来の区分値emp_typeもあります。取れる値はboard_member(役員)・full_timer・contract_worker・permatemp・part_timer・outsourcing_contractor・etcの7つで、実装のEnumに固定されています。「嘱託」「インターン」のようにテナントで独自に作った区分はここに収まりません。テナントで定義した部署や雇用形態を確実に指定するなら、先にsmarthr_list_departments()とsmarthr_list_employment_types()でIDを引く形になります。依頼を通すには、Claudeがこの順番で複数のツールを呼び分ける必要があります。

複数名を一度に頼むと、人数分だけこの流れが繰り返されます。一括登録用のツールはないので、50人分を頼めば呼び出しも50人分になります。

退職処理は復元手段がないことを前提にする

退職処理はsmarthr_delete_crew()が該当します。従業員IDだけを受け取って削除するツールで、44のツールの中に削除を取り消す復元用のものはありません。退職日や引き継ぎ状況を人間が確認してから、対象者名をClaudeに復唱させたうえで依頼する運用が現実的です。

部署は事情が違い、削除ツールがありません。代わりにsmarthr_discontinue_department()で廃止します。引数には「部署が存続していた最後の日付」をYYYY-MM-DD形式で渡す必要があり、日付を決めないまま「営業第二部を廃止して」と頼んでも実行できません。

部署を新しく作る側にも入力の制約があります。smarthr_create_department()のリクエストモデルは、部署名に/を含めるとバリデーションで弾きます。「営業部/東日本」のように階層をスラッシュで書いた依頼は、そのままでは通りません。階層は名前ではなく親部署のID(parent_id)で表す作りなので、親の部署を先に作ってIDを控えておく順序になります。

異動は従業員本体の更新で部署IDだけ渡す

「部署だけ変える」異動では、変更した項目だけを送る更新が向いています。名前にpartial_updateが付くツールは6種類だけですが、従業員本体の更新ツールも渡した項目だけを送ります。

異動は「従業員の所属部署」を変える操作なので、部署マスターの部分更新ではなく、従業員本体の更新です。smarthr_update_crew()はexclude_unsetで送信内容を作るため、department_idsだけ渡せば足ります。部署の名称変更(マスター側)に使うsmarthr_partial_update_department()は、人の異動には使えない点に注意が必要です。

「山田さんを企画部に異動」の依頼で、Claudeはsmarthr_search_crews()で従業員IDを引いてから更新に進む流れになります。現在の値を確認したいときはsmarthr_get_crew()を挟みます。渡さなかった項目はリクエストに含まれません。それでも、テスト用テナントで1人分を試しておくのが確実です。

検索と棚卸しで条件をどこまで絞れるか

smarthr_search_crews()が受け取るのは検索語(query)とページ設定だけです。氏名や社員番号のような文字列で探す用途には使えますが、雇用形態や日付での絞り込みは、こちらのツールではできません。

条件で絞るのはsmarthr_list_crews()のはずですが、ここにも落とし穴があります。クライアント実装(smarthr_client.py)が受け付ける条件は次のとおりです。

• 社員番号(emp_code)・性別(gender)
• 雇用形態(employment_type_id)・在籍状況(emp_status)
• 部署(department_id)
• 入社日の範囲(entered_at_fromとentered_at_to)
• 退職日の範囲(resigned_at_fromとresigned_at_to)

ただし、MCPツール側の定義はsmarthr_list_crews(page, per_page, **kwargs)で、これらの条件を個別の引数として公開していません。uv.lockで固定されたmcp 1.6.0のFastMCPに同じ定義を登録して確かめると、入力スキーマにはkwargsという必須の文字列引数が現れ、emp_statusのような名前で渡すと検証エラーになりました。kwargsの中に入れて渡しても、kwargs=...という1つのクエリ文字列として送られるだけで、絞り込みにはなりません。Claudeからは絞り込みが効かず、ページを送って全件を取り、Claude側で読む形になります。

契約の終了日で絞る条件は、クライアント実装にもありません。「今月末までに契約更新が必要な従業員」のような依頼は、一覧を取ったうえで、契約終了日のような項目を含む結果をClaude側で読んで判断することになります。どの項目に入っているかは、事前に1人分を取得して確認しておく必要があります。

従業員の一覧は1ページ10件が既定です。従業員が数百人いる会社で全件の棚卸しを頼めば、ページを送りながら複数回の呼び出しが走ります。棚卸しの前に人数を確認し、呼び出し回数の見込みを立てておくと安心です。

等級・職種の重複を洗い出す

等級(grade)・職種(job_category)・役職(job_title)は、名称が似た項目が残っていないかを確認したくなるマスターです。どれも取得・一覧・作成・更新・部分更新・削除のツールが揃っています。

「登録されている職種を全部見せて、名称が似ているものを教えて」と頼む場合は、smarthr_list_job_categories()で一覧を取得させ、その結果から重複候補を挙げさせる形になります。統合するかどうかは人間が判断し、確定した分だけ更新や削除を依頼する進め方が安全です。役職を新しく作るときは、序列を表すrankが必須で、値は1〜99999の範囲でなければバリデーションで弾かれます。「役職を序列の高い順に付けて」のような依頼では、Claudeが数値を決めて渡すことになるため、値の指定を依頼文に含めておくと確実です。

家族情報の追加で必要になる項目

扶養家族の追加・変更には、smarthr_create_dependent()などの家族情報ツールを使います。従業員IDを先に特定し、そのIDの下に家族情報を作る2段階の構造です。

クライアント実装のDependentCreateRequestでは、続柄ID(relation_id)・姓・名・生年月日(birth_at)・性別・同居か別居かの区分(live_together_type)が必須項目です。性別はmaleかfemale、同居区分はliving_togetherかliving_separatelyのみ受け付けます。性別はバリデーターがそれ以外の値を弾き、「'male' または 'female' を指定してください」というエラーになります。依頼文に「男性」と書いても、値への変換はClaudeが行う必要があります。「子どもを1人追加して、続柄は子」だけでは足りません。続柄も名前ではなくIDで、smarthr_list_relations()で一覧を引いて対応するIDを確認する手順が入ります。依頼文に生年月日・性別・同居か別居かまで含めておくと、聞き返しが減ります。

家族情報の一覧を取るsmarthr_list_dependents()も、smarthr_list_crews()と同じ**kwargs受けの定義です。従業員ID・ページ番号・件数以外の条件は、同じ理由で絞り込みとして働かない見込みです。一覧は1ページ10件が既定なので、家族の多い従業員では続きのページを取る呼び出しが要ります。

続柄の一覧を返すsmarthr_list_relations()だけは、既定が1ページ100件です。従業員や各マスターの一覧が10件なのとは既定値が違います。

他のMCPサーバーと組み合わせる

Claude Codeは1つのセッションで複数のMCPサーバーを同時に扱えます。SlackやGmailのMCPサーバーを併用すれば、「登録して招待メールを送ったら、人事チームのSlackに完了報告して」のように、SmartHRの操作と社内への連絡を一続きの依頼にできます。サーバーの選び方はおすすめMCPサーバー10選にまとめています。

個人のリポジトリを本番の人事データに向けるときの線引き

更新が止まっており、READMEも「各ツールが何を返すか」までは書いていません。SmartHR側のAPI仕様が変わったときに追従されるかどうかは、提供者次第です。次のように分けて考えると、導入の可否を判断しやすくなります。

作成・更新・削除・招待はいずれもSmartHR側のデータを実際に変更します。server.pyで数えると、44のツールのうちcreate・update・partial_update・delete・discontinue・inviteを名前に含む書き込み系が28本で、残る16本が取得・一覧・検索です。ツールの3分の2近くが書き込みなので、読み取り専用の使い方を想定していても、登録したサーバーには変更を実行できる口が開いています。運用に組み込む前に、次の点を決めておきます。

• 削除・廃止のツールを使う依頼では、対象を確認する一往復をはさむ
• 書き込み系のツールを使わない期間は、claude mcp remove smarthrでサーバーの登録を外しておく
• 月次の棚卸しのように定期実行する業務は、ツールが動かなくなったときに手作業へ戻せる手順を残す

書き込みを頼む前に「実行内容を復唱してから実行して」と添えておくと、誤操作に気づきやすくなります。MCPサーバー全般の安全な運用の考え方はMCPセキュリティガイドにまとめています。

まとめ

依頼文が通るかは、ツールの引数がIDや必須項目を求めているかで決まります。導入前に、テスト用テナントで入社登録・異動・家族追加の3つを1人分ずつ試し、Claudeが聞き返す項目を洗い出しておくと、本番での手戻りを減らせます。