Skip to main content
Glama
README.md
# kintai-plus-mcp

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

[マネーフォワード クラウド勤怠Plus](https://biz.moneyforward.com/attendance-plus/)(旧 AKASHI)の公開 API を、Claude などの AI アシスタントから使えるようにする [Model Context Protocol](https://modelcontextprotocol.io) サーバーです。

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

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

公開 API の仕様(公式): [マネーフォワード クラウド勤怠Plus 公開API 仕様](https://akashi.zendesk.com/hc/ja/articles/115000475854)

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

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

| 0.1.x | 1.0 |
|---|---|
| プロンプト `monthly_review` | `end_of_month`(`end_of_day` の月末版。`close_out` を案内する) |
| ツール `get_working_statuses` | `get_working_treatments`(勤務処理のラベル。打刻の `get_today_status` とは別) |

## できること

| ツール | 内容 |
|---|---|
| `get_my_profile` | 自分の従業員情報と権限 |
| `get_today_status` | 今日の状況(未出勤/勤務中/休憩中/退勤済み)と、ここまでの勤務時間 |
| `close_out` | 1 日または月の締め。打刻漏れ・法定の休憩不足・工数の過不足・残業の目安・アラートを、優先度つきの残件として 1 回で返す |
| `get_attendance_guide` | 就業ルール・法定休憩・打刻種別の説明(いまの勤務データではない) |
| `punch` 【書き込み】 | 打刻(出勤・退勤・直行・直帰・休憩入・休憩戻、テレワーク) |
| `get_stamps` | 打刻履歴(長い期間は自動で分割) |
| `get_working_records` | 勤務実績(労働区分・時刻・実働・休憩。31 日ごとに自動で分割)。任意の `staffIds` で管理下の従業員も取れる。省略時は本人 |
| `summarize_working_hours` | 実働合計・出勤日数・休日出勤日数・法定時間外の目安(月ごとの内訳つき) |
| `get_alerts` | アラート(打刻忘れ、遅刻、36協定 など) |
| `check_attendance_issues` | 打刻漏れチェック(退勤・出勤・休憩戻の打刻忘れ、12 時間超の日、勤務間インターバル 11 時間未満、休日出勤)。勤務実績にその時刻がある日は打刻漏れにしない。休憩が不明な経過時間は、12 時間超を情報にとどめる |
| `list_projects` / `list_tasks` / `get_my_projects` | プロジェクトとタスク |
| `get_manhours` | 工数(プロジェクト名・タスク名つき) |
| `save_manhours` 【書き込み】 / `delete_manhours` 【書き込み】 | 工数の登録・更新・削除 |

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

| ツール | 内容 |
|---|---|
| `list_staff` | 管理下の従業員の一覧(ID・氏名・社員番号・所属のみ) |
| `get_team_stamps` | 管理下の従業員の 1 日分の打刻と状況。過去日の退勤なしは「退勤打刻なし」で、その日の終わりまでは数えない |
| `team_close_out` | 管理下の 1 日または月の締め。勤務実績を主に、打刻漏れ・出勤の重複・法定休憩・11 時間のインターバル・残業の目安(36 時間と 45 時間)を 1 回で返す。問題が無い人は人数だけ。実績も打刻も無い人は別。アラートと工数未入力は見ない |
| `get_working_treatments` | 勤務処理のラベル(欠勤・出張など)。打刻の `get_today_status` とは別 |
| `get_project_members` | プロジェクトのメンバー |
| `find_overtime_risks` | 残業リスク検出(今月の法定時間外の目安と月末の着地予測。既定のしきい値は 45 時間) |

### 定型プロンプト

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

| プロンプト | 内容 |
|---|---|
| `end_of_day` | 退勤前チェック(`close_out` で今日の残件を見て、工数を埋めてから退勤を打刻) |
| `log_manhours` | 工数を入力する(日付と、やったことを渡せる) |
| `end_of_month` | 月末の締め(`close_out` で残件と残業の目安を 1 回で確認。0.1.x の `monthly_review`) |
| `team_status` | 管理者向け: チームの今日の状況と残業リスク |
| `team_end_of_month` | 管理者向け: チームの月末締め(`team_close_out` を 1 回) |

### リソース

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

| URI | 同じ内容のツール |
|---|---|
| `kintai://today` | `get_today_status`(今日の状態) |
| `kintai://close-out/month` | `close_out`(`scope=month`、今月) |
| `kintai://guide` | `get_attendance_guide`(就業ルール、法定休憩、打刻種別) |

## 必要なもの

- Node.js 22 以上
- クラウド勤怠Plus の API トークン(下の「API トークンの発行」)

## セットアップ

### 1. API トークンの発行

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

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

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

### 2. ログイン

```sh
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 で選択を中断します。

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

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

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

<details open>
<summary>Claude Desktop</summary>

`claude_desktop_config.json` に追加します。

```json
{
  "mcpServers": {
    "kintai-plus": {
      "command": "npx",
      "args": ["-y", "kintai-plus-mcp"]
    }
  }
}
```
</details>

<details>
<summary>Claude Code</summary>

```sh
claude mcp add kintai-plus -- npx -y kintai-plus-mcp
```
</details>

<details>
<summary>Cursor</summary>

`~/.cursor/mcp.json`(またはプロジェクトの `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "kintai-plus": {
      "command": "npx",
      "args": ["-y", "kintai-plus-mcp"]
    }
  }
}
```
</details>

<details>
<summary>VS Code(GitHub Copilot)</summary>

`.vscode/mcp.json`:

```json
{
  "servers": {
    "kintai-plus": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "kintai-plus-mcp"]
    }
  }
}
```
</details>

<details>
<summary>Codex CLI</summary>

`~/.codex/config.toml`:

```toml
[mcp_servers.kintai-plus]
command = "npx"
args = ["-y", "kintai-plus-mcp"]
```
</details>

## 設定(環境変数)

| 変数 | 既定 | 内容 |
|---|---|---|
| `KINTAI_PLUS_READ_ONLY` | `false` | `true` で書き込みツール(打刻・工数)を出さない |
| `KINTAI_PLUS_CONFIRM` | (下を参照) | 書き込み前の確認。`always`(毎回)/ `destructive`(削除だけ。未設定時の既定)/ `never`(確認しない)。設定してあると、`login` で保存した値より優先します |
| `KINTAI_PLUS_INCLUDE_LOCATION` | `false` | `true` で打刻の位置情報・IP を返す |
| `KINTAI_PLUS_REFRESH_DAYS` | `15` | 有効期限の残りがこの日数を切ったら再発行する(1〜30) |
| `KINTAI_PLUS_AUTO_REFRESH` | `true` | `false` で自動の再発行を止める |
| `KINTAI_PLUS_PERSIST_ENV_TOKEN` | `false` | `true` で、環境変数のトークンを保存し、期限が不明なら再発行する。環境変数の値は使えなくなることがある |
| `KINTAI_PLUS_CREDENTIAL_STORE` | `auto` | 保存先: `auto`(キーチェーン → ファイル)/ `keychain` / `file` |
| `KINTAI_PLUS_CREDENTIALS_FILE` | `~/.config/kintai-plus-mcp/credentials.json` | ファイル保存のパス(指定するとファイル保存になる) |
| `KINTAI_PLUS_LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` / `silent`(ログは stderr のみ) |
| `KINTAI_PLUS_MIN_INTERVAL_MS` | `300` | API リクエストの最小間隔(ミリ秒) |

### 書き込み前の確認

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

| 値 | 動き |
|---|---|
| `always` | 打刻・工数の保存・削除の前に確認する |
| `destructive` | 削除だけ確認する(既定) |
| `never` | 確認しない |

確認が必要なとき:

- クライアントが確認ダイアログ(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 も呼びません。**

```sh
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` も付きます)。

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

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

```json
{
  "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 からは修正・削除できません。** 間違えた場合は Web 画面から申請してください。このため、その日の打刻と矛盾する打刻(出勤済みなのに出勤、など)は実行しません。どうしても必要なときは AI に「強制して」と伝えてください(`force`)
- 残業時間は API にないため、「法定時間外の目安」(労働日・所定休日は 1 日 8 時間超、法定休日は全時間)として計算します。週 40 時間・変形労働時間制・フレックスは考慮しません。正式な値は勤怠Plus や給与計算で確認してください
- API の制約(勤務実績は 31 日、打刻は 6 ヶ月・1000 件、従業員一覧は 20 人/ページ、複数従業員の打刻は 1 日・50 人)は、サーバー側で分割・ページ送りします。1 回の呼び出しで取得できる期間には上限があります
- タイムゾーンは日本時間(Asia/Tokyo)固定です
- 人事マスタの書き込み(従業員の登録・削除、権限、異動など)は扱いません

## MCP クライアントの対応(2026-11 時点)

調べた範囲です。「未確認」は未対応という意味ではありません。

| 機能 | Claude Code | Cursor | VS Code | ChatGPT | Gemini CLI |
|---|---|---|---|---|---|
| ツール注釈(読み取り / 破壊的 / 冪等 / 外部) | あり | 未確認 | あり | あり | 未確認 |
| 書き込み前の確認(Elicitation) | あり | あり | あり | 未確認 | 未確認 |
| リソース(`kintai://...`) | あり | あり | あり | 未確認 | 一部 |
| structuredContent | 未確認 | 未確認 | 未確認 | あり | 未確認 |

注釈は全ツールに付いています。打刻は書き込みですが destructive ではありません(後から修正申請で直せます)。工数の削除は destructive です。成功したオブジェクトは、JSON のテキストと `structuredContent` の両方で返します。

## セキュリティとプライバシー

- トークンは OS のキーチェーン(macOS キーチェーン、Windows 資格情報マネージャー、Linux の Secret Service)に保存します。Linux で Secret Service がない場合は、再起動で消えるカーネルのキーリングではなく、ファイル(600)に保存します
- トークンは URL に載る API 仕様のため、ログ・エラーメッセージから必ず取り除きます
- 打刻の位置情報・IP は既定で AI に渡しません。従業員情報も ID・氏名・社員番号・所属に絞ります(メールアドレスは渡しません)
- `logout` は手元の認証情報を削除するだけです。トークン自体を無効にするには、マイページで操作してください

## 開発

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

設計の決定事項は [docs/design.md](./docs/design.md)、背景は [docs/adr/](./docs/adr/) にあります。

## ライセンス

[MIT](./LICENSE)

---

## English

**Unofficial** MCP server for the public API of "Money Forward Cloud Kintai Plus" (formerly AKASHI), a Japanese attendance management service.
This project is not affiliated with, endorsed by, or sponsored by Money Forward, Inc. All trademarks belong to their respective owners.

- Punch in/out, check today's status, close out a day or month in one call (`close_out`), view punch history, working records, alerts, and man-hours, and record man-hours
- Admin tools (staff list, team punches, team close-out via `team_close_out`, 勤務処理 labels via `get_working_treatments`, project members) are shown only to admins. `get_working_treatments` is not today's punch status (`get_today_status`)
- Runs locally over stdio: `npx kintai-plus-mcp`. Register your token first with `npx kintai-plus-mcp login`
- The token is stored in the OS keychain (or a 600-permission file) and reissued automatically before it expires. A token passed only via `KINTAI_PLUS_TOKEN` is not stored or reissued unless `KINTAI_PLUS_PERSIST_ENV_TOKEN=true` (reissue invalidates the previous token)
- Write confirmation has three levels. The default asks only before deleting man-hours. Punch and saving man-hours run without a dialog. Clients without elicitation get a preview until the tool is called again with `confirm: true`
- `kintai://today`, `kintai://close-out/month`, and `kintai://guide` mirror `get_today_status`, this month's `close_out`, and `get_attendance_guide`
- Location and IP address of punches are not sent to the AI by default
- Not supported: requests (申請) and schedules, because the public API does not provide them. Punches are recorded at the time the server receives them and cannot be edited via the API
- Requires Node.js 22+ and an API token issued from your Kintai Plus "My Page" (an admin must enable "公開API利用可否" for you)
- Official API reference (Japanese): https://akashi.zendesk.com/hc/ja/articles/115000475854
- License: MIT

TDQS

A3.9/5.0

Scored across 14 tools

Disambiguation4/5

Most tools target clearly distinct resources: punches vs. working records vs. man-hours vs. projects/tasks vs. alerts. The closest overlap is between get_alerts (attendance alerts) and check_attendance_issues (problem detection), but descriptions distinguish them (server-side alerts vs. computed checks). get_stamps vs get_working_records is also close but described distinctly.

Naming Consistency4/5

Nearly all tools follow a consistent verb_noun snake_case pattern (get_today_status, list_projects, save_manhours, check_attendance_issues). Minor deviations: 'punch' and 'get_stamps' use a bare noun rather than verb_noun, but overall highly predictable.

Tool Count4/5

14 tools is well-scoped for an attendance/man-hour domain covering status, punching, records, summaries, alerts, projects, tasks, and man-hour CRUD. Slightly heavy but each tool earns its place; no filler tools.

Completeness4/5

Strong coverage: punch lifecycle, status, history, working records, summaries, alerts, issue checks, and full man-hour CRUD (get/save/delete) with project/task lookups. Minor gaps include no way to correct punches via API (explicitly noted as a domain constraint) and no request/leave operations, but core workflows are complete.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues