PrismHR MCP

prismhr-mcp

PrismHR 向けのオープンソース Model Context Protocol（MCP）サーバーです。 Claude、Cursor、または MCP 互換の AI エージェントを PrismHR PEO プラットフォームに直接接続します。給与計算、福利厚生の登録、コンプライアンスレポート、売掛金／請求、保険会社向け EDI ファイル、Microsoft 365 の操作を自動化します。検証済みスキーマのツール、スコープで制御された同意、カスタム統合コード不要を実現します。

PrismHR に対して実際に機能する AI エージェントを求める PEO、ブローカー、給与計算担当者向けに構築されています。脆弱なスクリプトを寄せ集めたものではありません。

Simploy がメンテナンスしています。MIT ライセンスで、PyPI で配布され、プラグインに対応しています。PrismHR × エージェント型 AIの基盤レイヤーです。

mcp-name: io.github.nikulk2992-jpg/prismhr-mcp

キーワード： PrismHR API、PrismHR 統合、MCP サーバー、Model Context Protocol、PEO 自動化、給与計算の自動化、人事向け AI、PrismHR 向け Claude、エージェント型 AI、福利厚生登録の自動化、834 EDI、401(k) ファイル自動化、HRIS AI エージェント、PEO ソフトウェア統合。

---

なぜこれが必要なのか

PrismHR を運用している PEO はどこも、Python スクリプト、Postman コレクション、Playwright による自動化、単発の Node アプリを寄せ集めたフランケンシュタインのようなスタックに行き着きます。それぞれが、ログイン、セッションの維持、再試行ロジック、ページネーション、PrismHR 固有の癖（camelCase スキーマ、500 "No data found" の落とし穴、20 件単位の上限、通知されない 401）を再実装しています。

prismhr-mcp は、これらすべてを本番環境向けの MCP サーバーとして一元化します。AI エージェントがオーケストレーションを担い、サーバーが認証、キャッシュ、再試行、正規化、PEO のドメインロジックを管理します。どの PEO もこれを導入するだけで、自社の PrismHR テナントで生産性の高い AI エクスペリエンスを利用できます。連携コードも、推測も、幻覚によるエンドポイントも必要ありません。

対象者：

• PrismHR を運用しており、Claude／Cursor／ChatGPT Desktop を業務スタックに直接接続したい PEO
• 登録自動化を構築する福利厚生ブローカーや保険会社
• 脆弱な Postman／Playwright のワークフローを置き換えたい給与計算チーム
• 短い納期で PEO 向け AI パイロットを提供するコンサルタント

---

ステータス

中核機能は本番環境で利用できる状態です。PyPI と MCP Registry で公開されています。

• 認証＋セッション＋HTTP クライアント： 完了。1Password CLI 統合、scrypt で暗号化されたディスク上の認証情報キャッシュ、先回りして接続を維持する PrismHR セッション（ワークフローの途中で 401 が発生しません）、失敗時の自動更新、同時実行数の上限、ジッター付きバックオフによる再試行、500→空として扱う特殊ケースへの対応、ページネーション、バッチ処理。
• 検証済みスキーマのゲート： すべてのツールは UAT でのライブプローブに基づいています。推測したエンドポイントも、作り上げたフィールドもありません。 検証済みのレスポンス形状は 102 件で、増え続けています。
• 447 メソッドのカタログ： 18 のサービスにわたる PrismHR REST API 全体を索引化しています。meta_call を使うと、エージェントは検証済みの任意のメソッドを安全に呼び出せます。
• 接続時の同意システム： 15 スコープのマニフェスト、前提条件の展開とカスケード失効に対応する (peo, env) ごとの JSON 同意ストアを備えています。デフォルトの設定はすべて拒否です。ツールは呼び出し時にスコープを適用します。
• 本番環境の安全ゲート： 本番の PrismHR を接続先にするには PRISMHR_MCP_ALLOW_PROD=true が必要です。初回実行時に意図せず影響が及ぶのを防ぎます。
• MCP Registry に掲載： MCP 対応のすべてのクライアントから検出できます。
• テストスイート： pytest と respx によるテストがすべて成功します。

全体のロードマップは .planning/architecture.md を、有料プランの詳細は .planning/assistants-roadmap.md を参照してください。

---

PEO で実現できること

PrismHR テナントに接続すると、AI エージェント（Claude、ChatGPT、Cursor）は、ライブデータに対して以下のワークフローを実行できます。デフォルトでは読み取り専用で、書き込み操作はオプトインでスコープを指定します。

日次業務

• 新入社員オンボーディング監査 — 新入社員全員について、SSN、住所、E-Verify の承認、必須控除、差し押さえの設定に漏れがないか確認します。最初の給与支給前に問題を検出します。
• 給与バッチ健全性チェック — オープン中のすべてのバッチのステータスをリアルタイムで確認します。古い INIT、承認の停滞、支給日を過ぎても未処理のバッチ、マイナスの手取り額、伝票の欠落を検出します。
• 退職者クリーンアップ — 退職後のチェックリストです。最終給与の支給、控除の停止、福利厚生の終了、COBRA レコードの作成、PTO の支払い、ACH の無効化を確認します。
• 手動小切手監査 — 理由コードのない臨時小切手、過大な金額、一定期間内の重複、毎月繰り返されるパターンを検出します。

コンプライアンス

• ACA 設定の整合性 — PrismHR 自身が、1094-C／1095-C の罰金リスクの最大の原因として指摘している設定ミスを検出します。
• 1095-C 値の整合性監査 — 1095-C フォームの生成後にすべてを監査します。従業員が加入中にもかかわらずコード 1H が記載されている場合、セーフハーバーとの競合、ステータスタイプ変更によるコードのずれ、待機期間のコード誤り、2020 年より前の年度における ICHRA コードの使用を検出します。
• 扶養家族の補償年齢上限到達 — ACA の年齢基準を超えた扶養家族、または今後 30／60／90 日以内に基準に達する扶養家族を検出します。
• COBRA 適格性確認 — 適格事由、通知期間のカウントダウン、加入期限の警告を確認します。
• 差し押さえ支払い履歴 — 支払いのない有効な差し押さえ、期限超過の送金、複数の差し押さえにおける優先順位を確認します。
• W-2 準備状況チェック — 1 月に向けた事前確認です。SSN の登録と書式の正しさ、連邦源泉徴収の設定、YTD の妥当性を確認します。

照合

• 給与 YTD 照合 — 年初来の合計と伝票履歴の合計を一括で照合します。W-2 の時期が来る前に、気づきにくいずれを検出します。
• 941 四半期照合 — 四半期ごとに連邦税申告の数値を照合します。賃金、FIT、社会保障税、メディケア税、追加メディケア税が対象です。
• 福利厚生・控除監査 — 加入済みだが控除されていないもの、および控除済みだが加入していないものの不一致を検出します。気づきにくい保険料の漏れを確認します。
• 請求額と給与の洗浄監査 — 従業員ごとにプランレベルで確認します。
• 請求額と給与の照合（クライアントレベル） — 月次のコントローラー照合です。
• 401(k) マッチングルールのコンプライアンス — 雇用主のマッチング額とプランの計算式、402(g) 上限の監視、50 歳以上の追加拠出適格性を確認します。
• 401(k) 年末調整計算 — 拠出限度額に早期に達し、比例したマッチングを受けられなかった従業員に対する、年末時点の未払いマッチング額を計算します。

福利厚生＋売掛金

• FSA／HSA 拠出限度額トラッカー — IRS の 2026 年限度額を監視し、上限超過、上限接近、超過見込みを検出します。
• 退職金制度ローンの状況 — 債務不履行のリスク、返済期限超過のローン、みなし分配のリスクを確認します。
• 労災補償のリスク — 現在の賃金 × 料率 × 経験修正係数を使い、州ごと・クラスコードごとに保険料を推定します。
• 未払い請求書の経過期間 — 売掛金を期間別に分類し、リスクのあるクライアントにフラグを付けます。
• PTO 残高照合 — マイナス残高、上限超過、古い付与データ、クラス割り当ての欠落を確認します。
• 書類有効期限確認 — 今後 30／60／90 日以内に有効期限を迎える I-9 および本人確認書類を確認します。
• クライアント稼働開始準備状況 — 新規 PEO クライアント向けの給与処理前チェックリストと準備状況スコアです。

キャリア＋配布

• キャリア加入（834 5010） — 汎用ライターとキャリアごとの補足ガイド設定を提供します。Guardian モデルは稼働中です。BCBS Michigan、Sun Life EDX、Voya PDI、Empower PDI はパイロット版のロードマップに含まれています。
• W-2 配布アシスタント — 一括ダウンロード、書留郵便での発送、同意確認付き電子配信、SharePoint へのアーカイブをすべて組み合わせて利用できます。

各ワークフローは、重要度と修正のヒントを含む構造化された検出結果を返すため、AI エージェントはこれらを連結して、より高度なレポート（期末締めパック、年末申告パック、新規クライアント稼働開始パックなど）を作成できます。

ティア構成： OSS コアは無料です。上記のワークフローは有料の prismhr-mcp-simploy ティアで提供されます。ソースコードを利用可能で、PEO ごとのライセンスです。[email protected] までお問い合わせください。

---

エディション

prismhr-mcp は3つのティアで提供されています。Coreは永久に無料です。有料ティアでは、商用PEO向けのインテリジェンスが追加されます。

Tier 1 — prismhr-mcp (このリポジトリ、MIT、無料)

基盤となるエディションです。含まれる内容：

• キープアライブと自動更新に対応したPrismHRセッションマネージャー
• 447メソッドのカタログと、検証済みスキーマを使用する meta_call
• スコープに基づく同意、本番環境の安全性ゲート、暗号化された認証情報キャッシュ
• meta_find、meta_describe、meta_capabilities
• ライブUATに基づくクライアント、従業員、給与計算の読み取りツール
• MCP Registryへの掲載、PyPIでの配布

カスタムコードを一切書かずに、今すぐPrismHRテナントに対してClaudeを実行したい場合にご利用ください。

Tier 2 — prismhr-mcp-simploy (有料、ソース公開) — 現在開発中

PEOのワークフローをエンドツーエンドで実行する、名前付きAIアシスタントです。OSSコアを基盤とし、PEOごとにライセンスを提供します。

現在提供中：

• キャリア登録アシスタント — 汎用834 5010 EDIライターと、キャリア別の補足ガイド設定。Guardianモデルのプロトタイプが稼働中（8件のテストがすべて成功）。 BCBS Michigan、Sun Life EDX、Voya PDI、Empower PDIをPhase 1のパイロット候補として準備中です。次はSFTP配信と差分追跡に対応します。
• 401(k)ファイル自動化 — Empower PDI、Voya給与計算、Fidelityのテープ仕様固定幅フォーマット。

ロードマップ：

• 給与業務アシスタント — 無効化／訂正のワークフロー、控除の競合検出、時間外労働の異常フラグ、スーパーバッチ照合
• 福利厚生管理アシスタント — 福利厚生の選択内容の監査、COBRAの加入資格、ACAのステータス、キャリアとの同期検証
• コンプライアンスアシスタント — W2／941の照合、差し押さえの追跡、州税の設定、I-9監査、労災保険コード
• 売掛金／請求アシスタント — 請求と給与計算の監査、請求書の要約、雇用主の納税義務
• ブランド対応レポート — プラグイン可能なブランドとテンプレートのレジストリによるSimployブランドのPDF／XLSX（ホワイトラベル対応）
• Microsoft 365コネクター — Graph APIのメール、SharePointへのアップロード、Teamsへの投稿、Outlookのイベント／タスク

Tier 3 — prismhr-mcp-broker (有料、ホスト型) — 計画中

キャリア、ERP、EDIプロバイダーが、単一の統合を通じて任意のPrismHR PEOに接続できる、マルチテナント対応のホスト型MCPエンドポイントです。1つのエンドポイントで多数のテナントに対応し、コンプライアンスを一元管理します。Tier 2が2つ目のPEOに対応するまで延期されます。

Tier 2またはTier 3にご興味がある場合は、[email protected] までお問い合わせください。

---

クイックスタート — UATスモークテスト

現時点では、明示的にオプトインしない限りUATのみがサポートされます。本番環境は PRISMHR_MCP_ALLOW_PROD=true で保護されています。

1. インストール

cd C:\path\to\prismhr-mcp    # or wherever you cloned
uv sync --extra dev

2. 認証情報を設定する

.env.example を .env にコピーするか、環境変数を設定してください。次のいずれか1つを選びます。

方法A — 1Password CLI（推奨）：

$env:PRISMHR_MCP_ONEPASSWORD_VAULT = "YourVault"
$env:PRISMHR_MCP_ONEPASSWORD_ITEM_PRISMHR = "PrismHR UAT"

op CLIにサインイン済みである必要があります（op signin）。アイテムには username と password というラベルのフィールドが必要です（peoId は任意）。

方法B — 環境変数を直接設定（迅速、CIに適しています）：

$env:PRISMHR_MCP_USERNAME = "<your-api-username>"
$env:PRISMHR_MCP_PASSWORD = "<paste>"
$env:PRISMHR_MCP_PEO_ID   = "<your-peo-id>"

3. 動作確認

uv run python -c "from prismhr_mcp.server import build; b = build(); import asyncio; print([t.name for t in asyncio.run(b.server.list_tools())])"

ツールが9個表示されることを確認してください。

4. Claude Codeに登録する

Claude Codeの .mcp.json に追加します。

{
  "mcpServers": {
    "prismhr-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\path\\to\\prismhr-mcp", "prismhr-mcp"],
      "env": {
        "PRISMHR_MCP_ENVIRONMENT": "uat",
        "PRISMHR_MCP_USERNAME": "<your-api-username>",
        "PRISMHR_MCP_PASSWORD": "<paste or reference>",
        "PRISMHR_MCP_PEO_ID": "<your-peo-id>"
      }
    }
  }
}

Claude Codeを再起動してください。/mcp に prismhr-mcp が9個のツールとともに接続済みとして表示されます。

5. 最初の会話

You: Tell me about the prismhr-mcp server.
Claude: [calls meta_about] → explains what's available + commercial options.

You: What permissions does it want?
Claude: [calls meta_request_permissions] → shows 14 scopes grouped by category.

You: Grant everything recommended (reads only, no writes).
Claude: [calls meta_grant_permissions(accept_recommended_defaults=true)]

You: List all clients in UAT.
Claude: [calls client_list] → returns the full client roster.

6. テストを実行する

uv run pytest -q      # expect 60 passing

---

アーキテクチャの概要

┌──────────────────────────────────────────────────────────────┐
│ Claude / Cowork / any MCP client                             │
└──────────────────┬───────────────────────────────────────────┘
                   │ stdio (MCP JSON-RPC)
┌──────────────────▼───────────────────────────────────────────┐
│ prismhr-mcp server (FastMCP)                                 │
│   ├── Permissions (deny-default, scope-gated tools)          │
│   ├── Tool groups: meta • client • payroll • benefits        │
│   │                 compliance • billing • report • m365     │
│   ├── Runtime: PrismHR client, Graph client, SQLite cache    │
│   └── Auth: 1Password → scrypt-AES cache → session / MSAL    │
└────┬─────────────────────────────────────────────────┬───────┘
     │                                                 │
     ▼                                                 ▼
┌──────────────┐                           ┌──────────────────┐
│ PrismHR REST │                           │ Microsoft Graph   │
│ (UAT / Prod) │                           │ (Outlook / Teams /│
└──────────────┘                           │  SharePoint)      │
                                           └──────────────────┘

主な設計方針：

• ファクトリーと厳格なレジストリ。 ツールは server.build() を通じてのみ登録します。名前の重複や不明なグループ接頭辞がある場合、起動時に失敗します（インポート時に黙って処理されることはありません）。
• スコープはデフォルトで拒否。 ツールへのアクセスを有効にするには、ユーザーが meta_grant_permissions を実行する必要があります。前提条件は自動的に追加され、取り消しは連鎖します。
• 非同期を優先。 httpx.AsyncClient、asyncio.Semaphore(5)、非同期ツールを使用します。
• PrismHR固有の仕様に対応。 401では自動更新、リストエンドポイントの404では [] を返し、500 "No data found" では空の結果を返します。500が10回連続した場合は強制的に更新します。
• snake_caseの出力。 Pydanticの validation_alias=AliasChoices(...) を使うことで、PrismHRのcamelCaseペイロードをsnake_caseの出力に変換し、MCPツールのコントラクトにcamelCaseが漏れないようにします。
• (peo, env)ごとの同意。 UATから本番環境に切り替えても、許可設定は引き継がれません。

商用サポート

OSS のコアは今後もずっと無料です。Simploy はその上に、2 つの有料サービスを提供しています。

ソリューションアーキテクト — ホワイトラベル展開

PEO ブランド向けの prismhr-mcp のターンキー展開です。

• ブランド設定の作成（ロゴ、カラーパレット、タイポグラフィ、PDF フッター、法的免責事項）
• クライアントごとの SharePoint サイトのマッピング、および Azure AD / Graph テナントの設定
• PEO 固有のワークフロー向けのカスタム PrismHR ツール
• スプレッドシートやレガシースクリプトから MCP ツールへの移行
• PEO 運用チームのオンボーディング、および Claude/Cowork ワークフローのコーチング
• 上流リリースに合わせた四半期ごとの更新
• 優先的な問題対応、および担当者を指定した Slack/メール連絡窓口

社内で構築せずに Claude を中心とした運用を実現したい、クライアント数が 50～5,000 の PEO に最適です。 お問い合わせ先：[email protected]

エンタープライズサポート

OSS サーバーをすでに運用しているチーム向けの SLA 付きサポートです。

• Sev-1（本番環境の停止）に 4 時間以内に対応
• 年次セキュリティレビュー、および SOC-2 に適した展開ガイダンス
• 署名済みリリース成果物、および SBOM
• 非公開の脆弱性開示窓口

規制対象業界、または調達要件のある中規模・大規模 PEO に最適です。 お問い合わせ先：[email protected]

Claude には meta_about を通じて両方のサービスを表示できます。「prismhr-mcp にはどのような商用オプションがありますか？」と尋ねると、内容を説明します。

---

トラブルシューティング

No PrismHR credentials configured — 1Password アイテムの環境変数、または直接指定する PRISMHR_MCP_USERNAME/_PASSWORD の組み合わせを設定してください。

PrismHR login rejected (status=401) — ユーザー名、パスワード、または peo_id が間違っています。peo_id はテナントごとに異なります。PrismHR の管理者に確認してください。本番環境と UAT では値が異なります。

environment=prod requires PRISMHR_MCP_ALLOW_PROD=true — 安全ゲートによるメッセージです。準備ができたら、PRISMHR_MCP_ALLOW_PROD=true を明示的に設定してください。

PERMISSION_NOT_GRANTED — ツールが必要なスコープなしで呼び出されました。Claude に meta_request_permissions を実行させ、その後、必要なスコープを指定して meta_grant_permissions を実行させてください。

Claude Code の起動時にサーバーがすぐに終了する — ほとんどの場合、環境変数が設定されていません。ステップ 3 の正常性チェックで原因を特定してください。

---

ライセンス

MIT — LICENSE を参照してください。貢献を歓迎します。ロードマップについては .planning/ 内の計画ドキュメントをご覧ください。