> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moneru.us/llms.txt
> Use this file to discover all available pages before exploring further.

# API・MCP クイックスタート

> Moneruの公開REST APIとMCPへ安全に接続し、本人の家計データを読み取るまでの手順です。

Moneruは、外部アプリ向けのREST APIと、AIクライアント向けのMCP（Model Context Protocol）を提供します。どちらも、ログインしている本人が所有するデータだけを扱います。

<Info>
  REST APIはスクリプトやアプリから利用する場合に、MCPはCodexなどの対応AIクライアントから利用する場合に選びます。
</Info>

## はじめる前に

次のものを用意してください。

* Moneruのアカウント
* Moneruに登録済みの口座や明細
* REST APIを使う場合は、Moneruで発行したAPIキー
* MCPを使う場合は、Streamable HTTPとOAuth 2.1に対応したMCPクライアント

<Warning>
  APIキーは本人の家計データへアクセスできます。ソースコード、Git、ログ、チャットへ記録しないでください。共有端末では使わず、不要になったキーやMCP接続は失効させてください。
</Warning>

## 接続する

<Tabs sync={false}>
  <Tab title="REST API">
    <Steps>
      <Step title="APIキーを作成する">
        Moneruへログインし、[認証・APIキー管理リファレンス](https://moneru.us/api/auth/reference)からAPIキーを作成します。

        生のAPIキーが表示されるのは作成時だけです。安全なシークレット管理機能へ保存してください。
      </Step>

      <Step title="口座一覧を取得する">
        APIキーを環境変数 `MONERU_API_KEY` から渡し、本人の口座一覧を取得します。

        ```bash theme={null}
        curl --fail --silent --show-error \
          https://moneru.us/api/v1/accounts \
          --header "Authorization: Bearer ${MONERU_API_KEY}"
        ```

        成功すると、APIキー所有者の口座だけが返ります。キーがない、無効、または期限切れの場合は `401` になります。
      </Step>

      <Step title="利用できるAPIを確認する">
        [APIリファレンス](https://moneru.us/docs/api)でエンドポイントを確認できます。機械可読な契約は[OpenAPI 3.1](https://moneru.us/openapi.json)で公開しています。
      </Step>
    </Steps>

    <Note>
      `Authorization: Bearer` の代わりに `x-api-key` ヘッダーも利用できます。
    </Note>
  </Tab>

  <Tab title="MCP">
    <Steps>
      <Step title="Moneru MCPを登録する">
        MCPクライアントへ、次のStreamable HTTP URLを登録します。

        ```text theme={null}
        https://moneru.us/mcp
        ```

        Codex CLIでは次のコマンドで登録できます。

        ```bash theme={null}
        codex mcp add moneru_mcp --url https://moneru.us/mcp
        ```
      </Step>

      <Step title="OAuthで接続する">
        Codex CLIでは、次のコマンドで認証を開始します。

        ```bash theme={null}
        codex mcp login moneru_mcp
        ```

        ブラウザでMoneruへログインし、接続先と要求された権限を確認して許可します。読み取りだけでよい場合は `read` のみを許可してください。
      </Step>

      <Step title="家計データを読み取る">
        接続後、AIクライアントへ「今月の支出をカテゴリ別に集計して」のように依頼します。クライアントは、許可された範囲でMoneruのMCPツールを選びます。

        Codex CLIでは、次のコマンドで登録状態を確認できます。

        ```bash theme={null}
        codex mcp list
        ```
      </Step>
    </Steps>
  </Tab>
</Tabs>

## MCPの権限

`read` 権限では、次の情報を読み取れます。

* 明細
* 月次集計
* 継続支払い
* カテゴリ
* カレンダー集計

`write` 権限では、明細更新、カテゴリ作成、CSV取り込み、継続支払いの除外・復元を要求できます。

<Warning>
  `write` を許可しても、AIからの最初の書き込み要求はすぐには実行されません。Moneruの設定画面で変更内容を確認し、10分以内に承認した同一内容だけが1回実行されます。
</Warning>

## エンドポイント

| 用途          | URL                                                              |
| ----------- | ---------------------------------------------------------------- |
| REST API    | `https://moneru.us/api/v1`                                       |
| MCP         | `https://moneru.us/mcp`                                          |
| APIリファレンス   | [https://moneru.us/docs/api](https://moneru.us/docs/api)         |
| OpenAPI 3.1 | [https://moneru.us/openapi.json](https://moneru.us/openapi.json) |

## うまく接続できない場合

* REST APIが `401` を返す場合は、認証ヘッダー、キーの有効期限、利用している環境を確認してください。
* MCPの認証に失敗する場合は、クライアントから接続を削除してOAuth認証をやり直してください。
* `429` が返る場合は、レート制限の解除を待ってから再試行してください。
* REST APIの正確なリクエスト・レスポンス契約はOpenAPIを、MCPの最新ツール一覧と入力形式はクライアントのMCP discoveryを参照してください。