Kintai Plus (unofficial)

kintai-plus-mcp

非公式 の MCP サーバーです。株式会社マネーフォワードとは関係がなく、同社による確認・保証は受けていません。 「マネーフォワード クラウド勤怠Plus」「AKASHI」などの名称・商標は、それぞれの権利者に帰属します。

マネーフォワード クラウド勤怠Plus（旧 AKASHI）の公開 API を、Claude などの AI アシスタントから使えるようにする Model Context Protocol サーバーです。

「出勤して」「今月の残業はどれくらい？」「昨日の工数を設計 2 時間・実装 5 時間で入れて」のように話しかけるだけで、打刻・勤務実績の確認・工数入力ができます。

• 手元の PC で動くローカルの stdio サーバーです（トークンを第三者のサーバーに預けません）
• トークンは OS のキーチェーンに保存し、有効期限が近づくと自動で再発行します（環境変数で渡したトークンは、明示しない限り保存も再発行もしません）
• 打刻の位置情報・IP アドレスは、既定では AI に渡しません

公開 API の仕様（公式）: マネーフォワード クラウド勤怠Plus 公開API 仕様

1.0 からは、ツール名・引数・プロンプト名を互換性の約束とします。これらを壊す変更は、メジャーバージョンを上げるときだけ行います。まだ未確認の API の点は docs/api-notes.md の「未確認事項」にあります。

0.1.x から 1.0 で、次の名前だけ変えます。旧名では呼べません。

できること

管理者（企業管理者・一般管理者）には、次のツールも表示されます。一般の従業員には表示されません。

定型プロンプト

対応しているクライアントでは、メニューから次のプロンプトを呼び出せます（使うツールが公開されているときだけ表示）。

リソース

対応しているクライアントでは、次の URI をコンテキストとして読めます。中身はツールと同じです。リソースが無いクライアントは、右のツールを使ってください。

必要なもの

• Node.js 22 以上
• クラウド勤怠Plus の API トークン（下の「API トークンの発行」）

セットアップ

1. API トークンの発行

管理者が行うこと（一度だけ）: 従業員設定 > 対象の従業員の「変更」 > 利用機能設定 で、「公開API利用可否」を「利用する」にします。

本人が行うこと: マイページ > APIトークン で発行します。トークンの有効期限は 1 ヶ月と 1 日です。login で登録したトークンは、登録時と、期限が近づいたときに再発行します。

login で登録するトークンは、このツール専用にしてください。再発行すると、それまで使っていたトークンは使えなくなります。環境変数で渡すだけの場合は、既定では再発行しません（下の「環境変数でトークンを渡す」）。

2. ログイン

npx kintai-plus-mcp login

次を聞かれます。

• ログイン企業ID

• 接続先: ログイン後のブラウザの URL のドメインを、↑/↓ で選んで Enter で決めます。最初に選ばれているのは atnd.ak4.jp です。

  • atnd.ak4.jp（既定。https://atnd.ak4.jp/ でログインしている）
  • atnd-awj.ak4.jp（https://atnd-awj.ak4.jp/ でログインしている）

• 書き込み前の確認（接続先と同じ ↑/↓ と Enter。最初に選ばれているのは「削除だけ」）

  • 毎回確認する（すべての書き込み）
  • 打刻は確認なし、削除だけ確認（既定。工数の保存も確認しません）
  • 確認しない

• APIトークン（入力は表示されません）

端末でない入力（パイプなど）では、接続先は矢印ではなくドメインかその URL を 1 行で渡します。空行は atnd.ak4.jp です。--host で指定したときは接続先を聞きません。確認レベルは聞きません（保存してある値はそのまま。変えるときは下の環境変数か、対話の login）。Ctrl+C で選択を中断します。

疎通を確認してから保存します。状態の確認と削除は次のとおりです。

npx kintai-plus-mcp status   # 保存先・有効期限・権限（トークンは表示しません）
npx kintai-plus-mcp logout   # 保存した認証情報を削除

3. AI クライアントへの登録

{
  "mcpServers": {
    "kintai-plus": {
      "command": "npx",
      "args": ["-y", "kintai-plus-mcp"]
    }
  }
}

claude mcp add kintai-plus -- npx -y kintai-plus-mcp

{
  "mcpServers": {
    "kintai-plus": {
      "command": "npx",
      "args": ["-y", "kintai-plus-mcp"]
    }
  }
}

{
  "servers": {
    "kintai-plus": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "kintai-plus-mcp"]
    }
  }
}

[mcp_servers.kintai-plus]
command = "npx"
args = ["-y", "kintai-plus-mcp"]

設定（環境変数）

書き込み前の確認

既定は 打刻は確認なし、削除だけ確認 です。打刻と工数の保存はそのまま実行し、工数の削除だけ止めます。login で選んだ値は、認証情報とは別に保存します。

確認が必要なとき:

• クライアントが確認ダイアログ（Elicitation）に対応していれば、何をいつ登録・削除するかを示して承認をもらいます。断る、またはキャンセルすると、何も変えません。
• 対応していないクライアントでは、実行せずにプレビューを返します。同じツールを confirm: true で呼び直すと実行します。

KINTAI_PLUS_READ_ONLY=true のときは書き込みツール自体を出しません。打刻が今日の履歴と矛盾するときは、確認の前に拒否します（force: true はこれまでどおり）。

以前の KINTAI_PLUS_CONFIRM_WRITES（と、さらに古い CONFIRM_WRITES）は、KINTAI_PLUS_CONFIRM が無いときだけ読みます。true は always、false は never です。

環境変数でトークンを渡す（ボットなど）

login が使えないときは、環境変数だけで起動できます。既定では保存せず、再発行 API も呼びません。

KINTAI_PLUS_TOKEN=... KINTAI_PLUS_COMPANY_ID=... KINTAI_PLUS_HOST=atnd.ak4.jp npx kintai-plus-mcp

再発行 API は、渡したトークンを無効にして新しいトークンを返します。環境変数の値を自動で再発行すると、その値を共有している他のプロセスが突然使えなくなります。このサーバーは、明示しない限りそれをしません。

自動更新（期限が近づいたら再発行して保存）が必要なときは、このサーバー専用のトークンを npx kintai-plus-mcp login で登録してください。キーチェーンが使えない環境では、本人だけが読み書きできるファイル（パーミッション 600）に保存します。

環境変数のトークンを保存して再発行する動作は、KINTAI_PLUS_PERSIST_ENV_TOKEN=true を付けたときだけです。有効にすると、環境変数に書いたトークンは使えなくなることがあります。保存先にすでに認証情報があるときは、環境変数より保存先を優先します。

1 日・月末の締め（close_out）

「退勤前に見て」「今月締められる？」は close_out が 1 回で答えます。個別の確認ツールを順に呼ぶ必要はありません。scope は day（既定・今日）か month（既定・今月）です。日付は日本時間です。

残件が無い日は、こう返します（抜粋。実際には overtime や disclaimer も付きます）。

{
  "scope": "day",
  "ok": true,
  "readyToClose": true,
  "headline": "2026-10-27 は締められます。対応は不要です。",
  "counts": { "error": 0, "warning": 0, "info": 0 },
  "items": []
}

昼休みを打刻し忘れて休憩が 3 分しかない日（実働 8 時間 57 分）は、最初の項目が次のようになります。過去の打刻は API で直せないので、案内は Web の修正申請です。

{
  "ok": false,
  "headline": "先に 1 件対応してください。items を priority 順に処理してください。",
  "items": [
    {
      "priority": 1,
      "severity": "error",
      "code": "short_break",
      "date": "2026-10-26",
      "title": "休憩が 3 分しかありません",
      "detail": "打刻上の休憩は 3 分、実働は 8:57。労働基準法: 労働時間が 6 時間を超えたら休憩 45 分以上、8 時間を超えたら 60 分以上（ちょうど 6 時間・8 時間は含まない）。必要 60 分、あと 57 分足りません。",
      "action": "この日はすでに終わっているので、今 punch しても休憩は増えません。この打刻は API では修正できません。勤怠Plus の Web 画面から修正申請（打刻修正）をしてください。punch は呼ばないでください（今の時刻で新しい打刻が増えるだけです）。"
    }
  ]
}

今日がまだ休憩中なら、code は open_break で、次の操作は punch（type=break_end）です。修正申請ではありません。

限制

• 不支持申请（加班、休假、打卡修正等）和日程安排（因为公开 API 不提供这些功能）
• 打卡记录的时间以服务器收到请求的时间为准，且无法通过 API 修改或删除。 如果打卡有误，请通过网页申请更正。因此，不会执行与当天打卡状态矛盾的打卡操作（例如，已经打过上班卡却再次打上班卡）。确实需要时，请告诉 AI“强制执行”（force）
• API 不提供加班时间，因此会按“法定工时之外的参考值”（工作日和规定休息日超过每天 8 小时，法定休息日为全部工时）进行计算。不考虑每周 40 小时、弹性工时制度和弹性工作制。请通过勤怠Plus 或工资计算确认正式数值
• API 的限制（工作实绩为 31 天，打卡记录为 6 个月、1000 条，员工列表为每页 20 人，多名员工的打卡记录为每天 50 人）由服务端分批处理并分页获取。单次调用可获取的时间范围有限
• 时区固定为日本时间（Asia/Tokyo）
• 不处理人事主数据的写入操作（员工注册、删除、权限、调动等）

MCP 客户端支持情况（截至 2026-11）

以下为调查所得。“未确认”不代表不支持。

所有工具都带有注释。打卡属于写入操作，但不具破坏性（之后可通过更正申请修正）。删除工时属于破坏性操作。成功的对象会同时以 JSON 文本和 structuredContent 返回。

安全与隐私

• 令牌会保存在 OS 密钥链（macOS 钥匙串、Windows 凭据管理器、Linux Secret Service）中。如果 Linux 上没有 Secret Service，则会保存到文件（600），而不是重启后会清除的内核密钥环
• 由于 API 规范要求在 URL 中传递令牌，因此会从日志和错误消息中将其彻底删除
• 默认不会向 AI 传递打卡位置和 IP。员工信息也仅限于 ID、姓名、员工编号和所属部门（不会传递电子邮件地址）
• logout 只会删除本地凭据。若要使令牌失效，请在个人页面中操作

开发

pnpm install
pnpm test        # Vitest（モックと架空のフィクスチャのみ）
pnpm lint        # Biome
pnpm typecheck
pnpm build       # tsdown
pnpm e2e         # 実環境を叩く手動 E2E（読み取りのみ。手元でだけ実行）

设计决策见 docs/design.md，背景信息见 docs/adr/。

许可证

MIT

English

非官方 MCP 服务，用于访问日本考勤管理服务“Money Forward Cloud Kintai Plus”（原 AKASHI）的公开 API。 本项目与 Money Forward, Inc. 无关联，也未获其认可或赞助。所有商标均属于各自所有者。

• 打上班卡/下班卡，查看今天的状态，一次调用即可完成每日或每月结算（close_out），查看打卡历史、工作记录、提醒和工时，并记录工时
• 管理员工具（员工列表、团队打卡记录、通过 team_close_out 进行团队结算、通过 get_working_treatments 获取勤務処理标签、项目成员）仅对管理员显示。get_working_treatments 不是今天的打卡状态（get_today_status）
• 在本地通过 stdio 运行：npx kintai-plus-mcp。请先使用 npx kintai-plus-mcp login 注册令牌
• 令牌会保存在 OS 密钥链（或权限为 600 的文件）中，并在到期前自动重新签发。仅通过 KINTAI_PLUS_TOKEN 传入的令牌不会被保存或重新签发，除非设置 KINTAI_PLUS_PERSIST_ENV_TOKEN=true（重新签发会使先前的令牌失效）
• 写入确认分为三个级别。默认仅在删除工时前询问。打卡和保存工时不会弹出对话框。不支持 elicitation 的客户端会先显示预览，直到再次调用工具并传入 confirm: true
• kintai://today、kintai://close-out/month 和 kintai://guide 分别对应 get_today_status、本月的 close_out 和 get_attendance_guide
• 默认不会向 AI 传递打卡的位置和 IP 地址
• 不支持申请和日程安排，因为公开 API 不提供这些功能。打卡记录的时间以服务器收到请求的时间为准，且无法通过 API 修改
• 需要 Node.js 22+ 和从 Kintai Plus 的“个人页面”签发的 API 令牌（管理员必须为你启用“公开API利用可否”）
• 官方 API 参考（日语）：https://akashi.zendesk.com/hc/ja/articles/115000475854
• 许可证：MIT