Bill Tracker

Bill Tracker エージェントプラグイン

AI エージェントを Bill Tracker に接続できます。Bill Tracker は、LINE リマインダー機能を備えた個人向けの請求管理ツールです。接続すると、ご自身の Bill Tracker アカウントを通じて、支払期限や期限超過の請求を確認したり、支払いを記録したり、請求を追加・編集したり、支出を要約したりできます。

このリポジトリには、プラグイン、コネクター設定、エージェントスキルが含まれています。これらはすべて、次の 1 つのリモート MCP サーバーを参照します。

https://bills.jirawat.dev/mcp

メモ

Bill Tracker MCP サーバーは 2026 年 10 月 20 日にデプロイされました。公開メタデータと OAuth サインインチャレンジは、デプロイ時のスモークチェックに合格しました。 公式 JavaScript SDK を使用した Google サインインと 21 件の実環境 OAuth/MCP チェックに合格しました。チェックには、請求の書き込み、トークンの更新、取り消しが含まれています。ユーザーはブラウザーでの LINE QR サインインも確認し、請求台帳にアクセスしました。以下の各クライアント設定については、個別の実環境での互換性チェックがまだ必要です。

目次

• このリポジトリの内容
• 開始する前に
• サインイン、権限、プライバシー
• クライアントを選ぶ
• インストール
• ヘッドレスエージェント：個人用アクセストークン
• エージェントでできること
• ツールの変更と非推奨化
• トラブルシューティング
• リポジトリの構成
• このリポジトリのメンテナンス
• ライセンス

このリポジトリの内容

• 1 つのプラグインに、MCP サーバーと billing-tracker エージェントスキルがまとめられています。Claude Code、Codex、ChatGPT デスクトップアプリ、Cursor、VS Code、GitHub Copilot CLI、Gemini CLI、Antigravity CLI にネイティブにインストールできます。
• プラグインマーケットプレイスを使うと、Claude Code、GitHub Copilot CLI、VS Code、Codex からこのリポジトリをマーケットプレイスとして追加し、プラグインを最新の状態に保てます。
• 公式 MCP Registry 用の server.json。
• MCP サーバーに直接接続するクライアント用のコピー＆ペースト可能な設定：Claude アプリ、ChatGPT、Windsurf、Cline、Zed、stdio のみをサポートするクライアント。
• エージェントに請求ツールの適切な使い方を教える、ポータブルな エージェントスキル。一般的なタスク、破壊的な変更の前の確認、日付とタイバーツ金額の扱いが含まれています。

すべての設定で、サーバー名は bills です。

開始する前に

• Bill Tracker アカウント。 Bill Tracker で Google または LINE を使って一度サインインし、アカウントを作成してください。
• リモートサーバーに対応した MCP クライアント。 サーバーは OAuth サインインを伴う Streamable HTTP トランスポートを使用します。以下のクライアントはすべてこれに対応しています。ローカル（stdio）サーバーのみ起動できるクライアントでは、mcp-remote ブリッジを使用できます。
• 最新のクライアント。 サーバーは、現在のクライアントが使用する標準の initialize ハンドシェイクを通じて、MCP プロトコルリビジョン 2025-11-25（推奨）と 2025-06-18 に対応します。クライアントが initialize で別のリビジョンを提示した場合、サーバーは 2025-11-25 を返します。その後、続行できるかどうかはクライアントが判断します。サポート対象外の MCP-Protocol-Version ヘッダーを含むその他のリクエストには、エラー -32022 が返されます。サーバーは Streamable HTTP のみを使用し、従来の HTTP+SSE トランスポートには対応していません。そのため、2025-03-26 以前のリビジョンにしか対応していないクライアントは接続できない場合があります。

サインイン、権限、プライバシー

• ご自身のアカウントでサインインします。 エージェントが初めて接続すると、Bill Tracker のサイトがブラウザーウィンドウで開きます。アプリで使用しているものと同じ Google または LINE アカウントでサインインし、エージェントの名前と要求する権限が表示される同意画面を確認してください。クライアント ID、シークレット、API キーは必要ありません。クライアントは、標準の MCP 認可（PKCE を使用する OAuth 2.1、Client ID Metadata Documents または Dynamic Client Registration によるクライアント登録）を通じて、独自にサインインフローを検出します。
• 表示されるのはご自身の請求書だけです。 すべてのリクエストは、サインインしたアカウントとして実行されます。ご自身のアカウントに接続したエージェントが、他の人の請求書にアクセスすることはできません。
• 権限は段階的に付与されます。 デフォルトでは、初回のサインイン時に bills:read、bills:write、offline_access が要求されます。これにより、ブラウザーで再度サインインしなくても、クライアントがセッションを更新できます。Codex など一部のクライアントは、提示されたすべての権限を最初に要求します。エージェントが追加の権限を必要とするツールを初めて使用するとき、サーバーがその権限を要求し、クライアントが同意画面を再度開くか、サーバーへの再サインインを求めます。
• アカウントの削除には必ず別途承認が必要です。 サインイン中に account:delete 権限を要求できるクライアントはありません。エージェントにアカウントの削除を依頼した場合、最初の試行は拒否されます。その後、 設定 > 接続済み AI エージェント を開き、最近サインインした後に、専用の同意画面で削除を承認してください。この権限は、最初のサインイン時刻から 5 分後に期限切れになります。承認やコード交換によって期限がリセットされることはありません。リフレッシュトークンは発行されません。
• 任意のエージェントを接続解除できます。 Bill Tracker の 設定 > 接続済み AI エージェント を開くと、接続済みのエージェントと個人用アクセストークンをすべて確認でき、どれでも取り消せます。すべてのデバイスで Bill Tracker からサインアウトしても、エージェントは接続解除されません。このページで取り消してください。
• 破壊的な操作には確認が必要です。 リクエストに明示的な確認が含まれていない限り、サーバーは請求書の削除、LINE の連携解除、アカウントの削除を拒否します。また、付属のスキルは、まずユーザーに確認するようエージェントに指示します。
• このリポジトリにデータやシークレットは保存されません。 含まれているのは設定と手順のみです。サインイントークンは MCP クライアントに保存され、請求書は Bill Tracker に保持されます。

クライアントを接続する前に、サービスのプライバシーポリシーと 利用規約をお読みください。

権限	エージェントに許可される操作
bills:read	請求書と概要の一覧表示、検索、閲覧。chat.run の読み取りコマンドも含みます
bills:write	請求書の追加と編集、支払いの記録、金額の確認、支払いの予定設定
bills:delete	請求書の削除
reports:read	支出レポートの閲覧
account:read	すべてのデータのエクスポート
account:manage	すべてのデバイスでのサインアウト、LINE リマインダーのオン／オフ、LINE の連携解除
account:delete	Bill Tracker アカウントの削除。最近サインインした後に別途承認が必要です。サインインから 5 分後に期限切れとなり、リフレッシュはできません
line:read	LINE が連携されているか、リマインダーがオンかどうかの確認
chat:read	LINE チャットボットのコマンドを実行せずに解析。請求書の閲覧はできません
chat:write	データを読み取るだけのコマンドも含め、LINE チャットボットの任意のコマンドを実行。削除には bills:delete も必要です
offline_access	サインイン状態を維持し、ブラウザーで再度サインインせずにセッションを更新

クライアントを選択

クライアント	推奨セットアップ	スキルを含む
Claude Code	このマーケットプレイスのプラグイン	はい
Claude apps (claude.ai、Claude Desktop、モバイル)	カスタムコネクター	別途アップロードしてください
ChatGPT (ウェブ版のBusiness、Enterprise、Edu)	プラグインとして作成するカスタムMCPサーバー	いいえ
Codex (CLI、IDE拡張機能、ChatGPTデスクトップアプリ)	このマーケットプレイスのプラグイン	はい
Cursor	ワンクリックインストールリンク、またはローカルプラグイン	プラグインに含まれます
VS Code and GitHub Copilot	ワンクリックインストールリンク、またはソースからのプラグイン	プラグインに含まれます
GitHub Copilot CLI	このマーケットプレイスのプラグイン	はい
Gemini CLI	拡張機能	はい
Antigravity CLI	プラグイン	はい
Windsurf	mcp_config.json エントリー	いいえ
Cline	リモートサーバー	いいえ
Zed	context_servers エントリー	いいえ
Stdio-only clients	mcp-remote ブリッジ	いいえ

Agent Skillsに対応しているエージェントなら、どれでもスキルを追加できます。 スキルのみを参照してください。クライアントごとにセットアップは1つだけ使用してください。プラグインをインストールしたうえでサーバーも手動で追加すると、すべてのツールが二重に登録されます。

インストール

Claude Code

MCPサーバーとスキルを追加するプラグインをインストールします。Claude Code内で次を実行します。

/plugin marketplace add jirawatp/billing-tracker-agent-plugins
/plugin install billing-tracker@billing-tracker

または、ターミナルから実行します。

claude plugin marketplace add jirawatp/billing-tracker-agent-plugins
claude plugin install billing-tracker@billing-tracker

続いて /reload-plugins を実行するか、Claude Codeを再起動し、/mcp を開いて plugin:billing-tracker:bills を選択し、「Authenticate」を選びます。

サーバーのみをすべてのプロジェクトに追加するには、次を実行します。

claude mcp add --transport http --scope user bills https://bills.jirawat.dev/mcp
claude mcp login bills

ブラウザーのないマシンでは、claude mcp login bills --no-browser を実行すると サインインURLが表示され、リダイレクトURLを貼り付けるよう求められます。

ツールの実行時に「needs additional permissions」というエラーが表示された場合は、/mcp を開き、 サーバーを再認証して追加の権限を許可してください。

Claude apps (claude.ai, Claude Desktop, mobile)

Bill Trackerをカスタムコネクターとして追加します。カスタムコネクターは Free（カスタムコネクター1つ）、Pro、Max、Team、Enterpriseの各プランで利用でき、 追加するとclaude.ai、Claude Desktop、Cowork、モバイルアプリで使用できます。

1. Customize > Connectors に移動し、+ Add、次に Add custom connector を選択します。
2. 名前に Bill Tracker、URLに https://bills.jirawat.dev/mcp を入力し、 Continue を選択します。
3. Authentication で Sign in now を選択します。OAuth client では、 Use Claude's published identity (Recommended) のままにします。 Request headers は空欄にします。
4. Add を選択し、開いたウィンドウでGoogleまたはLINEにサインインします。
5. チャットで、Connectors の下にある + メニューからコネクターを有効にします。

TeamおよびEnterpriseプランでは、オーナーが組織設定でコネクターを追加し、 各メンバーがそれぞれ自分のBill Trackerアカウントを接続します。Claudeはお使いのコンピューターではなく、 Anthropicのクラウドからサーバーに接続します。

スキルも追加するには、Settings > Capabilities で Code execution and file creation を有効にし、billing-tracker フォルダーを含むZIPを作成して、Customize > Skills で + > Create skill > Upload a skill を選択してアップロードします。

git clone https://github.com/jirawatp/billing-tracker-agent-plugins
cd billing-tracker-agent-plugins/skills
zip -r billing-tracker.zip billing-tracker

ChatGPT

完全なツールサポートを備えたカスタム MCP サーバーは、ChatGPT Business、Enterprise、Edu のウェブ版のみで利用できます。Business では、ワークスペースの管理者とオーナーのみ追加できます。Enterprise と Edu では、管理者と、管理者が許可したメンバーが追加できます。Pro アカウントでは、読み取りと取得のみ可能なアクセスでカスタム MCP サーバーに接続できます。そのため、Bill Tracker のデータを変更するツールは利用できません。

1. ChatGPT で Plugins を開き、+ ボタンを選択してから、Add custom MCP server を選択します。
2. 名前に Bill Tracker を入力し、Connection の下に URL https://bills.jirawat.dev/mcp を入力します。
3. 認証には OAuth を選択します。ChatGPT がサーバーからサインイン設定を取得するため、クライアント ID とシークレットは空欄のままにします。
4. リスクに関する警告を確認し、I understand and want to continue を選択してから、Create as a plugin を選択します。
5. 検出されたツールを確認してプラグインをインストールし、求められたら Google または LINE でサインインします。
6. 新しいチャットで @ と入力し、Bill Tracker を選択します。

ワークスペースで共有するには、管理者またはオーナーがプラグインを公開します。ChatGPT は、プラグインの権限に応じて書き込み操作の確認を求めます。

Codex（CLI、IDE 拡張機能、ChatGPT デスクトップアプリ）

Codex CLI、Codex IDE 拡張機能、ChatGPT デスクトップアプリは ~/.codex/config.toml を共有するため、設定は一度だけ行います。MCP サーバーとスキルを追加するプラグインをインストールします。

codex plugin marketplace add jirawatp/billing-tracker-agent-plugins
codex plugin add billing-tracker@billing-tracker

マーケットプレイスを追加した後は、ChatGPT デスクトップアプリの Plugins ディレクトリからプラグインをインストールすることもできます。

サーバーのみを追加するには、次のコマンドを実行します。

codex mcp add bills --url https://bills.jirawat.dev/mcp

これにより、~/.codex/config.toml に次の内容が書き込まれます。

[mcp_servers.bills]
url = "https://bills.jirawat.dev/mcp"

codex mcp login bills でサインインします（リモートマシンでは --no-browser を追加します）。または、デスクトップアプリか IDE 拡張機能の MCP サーバー設定で、サーバーの横にある Authenticate を選択します。Codex は、サーバーが提示するすべての権限を要求します（アカウントの削除が要求されることはありません）。サインインしたまま基本的な権限のみを付与するには、codex mcp login bills --scopes bills:read,bills:write,offline_access を実行します。

Cursor

ボタンを押すと Cursor が開き、確認を求められます。Cursor のディープリンクと同じインストールリンクは次のとおりです。

cursor://anysphere.cursor-deeplink/mcp/install?name=bills&config=eyJ1cmwiOiJodHRwczovL2JpbGxzLmppcmF3YXQuZGV2L21jcCJ9

または、サーバーを ~/.cursor/mcp.json（すべてのプロジェクト）か .cursor/mcp.json（1 つのプロジェクト）に追加します。

{
  "mcpServers": {
    "bills": {
      "url": "https://bills.jirawat.dev/mcp"
    }
  }
}

サーバーが初めて接続するときに、Cursor がサインインフローを開始します。サーバーの管理や再サインインは、Customize から行います。

スキル付きのプラグインについては、Cursor は Cursor Marketplace とチームのマーケットプレイスからプラグインをインストールします。Bill Tracker がそこに掲載されるまでは、ローカルプラグインとして読み込み、その後 Cursor を再起動するか、Developer: Reload Window を実行してください。

git clone https://github.com/jirawatp/billing-tracker-agent-plugins ~/.cursor/plugins/local/billing-tracker

Teams および Enterprise プランでは、管理者がローカルプラグインのインポートを許可する必要があります。

VS Code と GitHub Copilot

または、ターミナルから実行します。

code --add-mcp '{"name":"bills","type":"http","url":"https://bills.jirawat.dev/mcp"}'

ワークスペースの .vscode/mcp.json、またはユーザー用の mcp.json に追加することもできます （MCP: Open User Configuration を実行します）。

{
  "servers": {
    "bills": {
      "type": "http",
      "url": "https://bills.jirawat.dev/mcp"
    }
  }
}

サーバーの初回起動時に、VS Code からサインインを求められます。 MCP: List Servers を使うと、サーバーの起動、停止、再サインインができます。

スキルを含むプラグインを使うには、chat.plugins.enabled 設定が オンになっていることを確認し、Chat: Install Plugin From Source を実行して、 https://github.com/jirawatp/billing-tracker-agent-plugins を入力します。 マーケットプレイス経由で更新を受け取るには、このリポジトリを chat.plugins.marketplaces 設定に追加し、拡張機能ビューから Bill Tracker を インストールします（@agentPlugins を検索します）。

{
  "chat.plugins.marketplaces": [
    "jirawatp/billing-tracker-agent-plugins"
  ]
}

GitHub Copilot CLI

MCP サーバーとスキルを追加するプラグインをインストールします。

copilot plugin marketplace add jirawatp/billing-tracker-agent-plugins
copilot plugin install billing-tracker@billing-tracker

サーバーのみを追加するには、次のようにします。

copilot mcp add --transport http bills https://bills.jirawat.dev/mcp

サーバーに needs-auth と表示されたら、Copilot CLI で /mcp auth bills を実行して サインインします。VS Code でも、Copilot CLI で追加したプラグインとサーバーが認識されます。

Gemini CLI

Gemini CLI は現在、Gemini Code Assist と API キーのユーザーに対応しています。個人の Google アカウントは、2026 年 6 月に Antigravity CLI に移行しました。MCP サーバーとスキルを追加する 拡張機能をインストールします。

gemini extensions install https://github.com/jirawatp/billing-tracker-agent-plugins

Gemini CLI を再起動し、/mcp auth bills を実行してサインインします。後で更新するには、 gemini extensions update billing-tracker を実行します。

サーバーのみを追加するには、次のようにします。

gemini mcp add --scope user --transport http bills https://bills.jirawat.dev/mcp

Antigravity CLI

MCP サーバーとスキルを追加するプラグインをインストールします。

agy plugin install https://github.com/jirawatp/billing-tracker-agent-plugins

サインインするには、/mcp を実行して bills を選択し、Authenticate を選びます。 ブラウザーでサインインを完了したら、表示されたコードをターミナルに貼り付けます。

serverUrl を ~/.gemini/config/mcp_config.json に書き込むサーバーのみを追加するには、次のようにします。

agy mcp add bills https://bills.jirawat.dev/mcp

Gemini CLI 拡張機能をすでにインストールしている場合は、agy plugin import gemini で変換できます。

Windsurf

Cascade の MCP メニューで Open MCP config file を選択し（現在のバージョンでは ~/.config/devin/mcp_config.json、Windows では %AppData%\devin\mcp_config.json です。古いバージョンでは ~/.codeium/windsurf/mcp_config.json が使われます）、次を追加します。

{
  "mcpServers": {
    "bills": {
      "serverUrl": "https://bills.jirawat.dev/mcp"
    }
  }
}

MCP パネルの更新ボタンを押します。サーバーを初めて使用するときに、Cascade からサインインを求められます。

Cline

Cline パネルで MCP Servers を開き、次に Remote Servers タブを開きます。 名前に bills、URL に https://bills.jirawat.dev/mcp を入力し、 Streamable HTTP を選択して、Add Server を選びます。Cline からサーバーに認証が必要だと通知されたら、 Authenticate を選択し、ブラウザーでサインインします。

代わりに設定ファイルを編集する場合（拡張機能では Configure MCP Servers、 Cline CLI では ~/.cline/data/settings/cline_mcp_settings.json）：

{
  "mcpServers": {
    "bills": {
      "type": "streamableHttp",
      "url": "https://bills.jirawat.dev/mcp",
      "disabled": false,
      "autoApprove": []
    }
  }
}

"type": "streamableHttp" を維持してください。これがないと、Cline はこのサーバーがサポートしていない レガシーな SSE トランスポートを使用します。

Zed

Settings > AI > MCP Servers を開き、Add Server、続いて Add Remote Server を選択します。または、設定ファイルに次を追加します （zed: open settings file）。

{
  "context_servers": {
    "bills": {
      "url": "https://bills.jirawat.dev/mcp"
    }
  }
}

Authorization ヘッダーを設定していない場合、Zed は標準の MCP サインインフローを実行します。 Zed が ACP 経由で実行する外部エージェントは、そのサインイン情報を共有しません。 それらのエージェントでは、サーバーを直接設定してください。

その他のクライアント（stdio のみ）

ローカル MCP サーバーしか起動できないクライアントでは、ブリッジとして mcp-remote を実行してください。Node.js が必要です。サインインのためにブラウザーを開き、トークンを ~/.mcp-auth に保存します。クライアントのプロトコルハンドシェイクは変更せずにそのまま転送するため、クライアント自体が MCP 2025-06-18 以降に対応している必要があります。

{
  "mcpServers": {
    "bills": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://bills.jirawat.dev/mcp",
        "--transport",
        "http-only"
      ]
    }
  }
}

これは、Claude Desktop のローカル claude_desktop_config.json を含む、ほとんどのクライアントが使用する mcpServers 形式です（この場合は、カスタムコネクターを使うほうが適しています）。

スキルのみ

billing-tracker スキルは Agent Skills specification に準拠しているため、スキルに対応するエージェントであれば、上記のいずれかのサーバー構成と併用できます。 skills CLI を使う場合：

npx skills add jirawatp/billing-tracker-agent-plugins

インストール先のエージェントを選択するよう求められます。現在のプロジェクトではなくユーザー用にインストールするには、-g を追加してください。skills/billing-tracker をエージェントのスキルフォルダーにコピーすることもできます。

ヘッドレスエージェント：個人用アクセストークン

ブラウザーを開けないスクリプト、CI ジョブ、エージェントでは、OAuth の代わりに個人用アクセストークンを使用できます。

1. Bill Tracker の Settings > Connected AI agents を開き、Create personal access token を選択します。名前を付け、権限と有効期限を選択して、トークンをコピーします。トークンが表示されるのは一度だけです。
2. たとえば、BILL_TRACKER_TOKEN という環境変数などにシークレットとして保存します。
3. すべてのリクエストで、ベアラートークンとして送信します。

Authorization: Bearer <token>

サーバーは、個人用アクセストークンを、選択した権限を持つサインイン済みセッションとまったく同じように扱います。選択した日付に有効期限が切れます。同じ設定ページで取り消すか、置き換えてください。

Claude Code。 シングルクォートを使うと、${BILL_TRACKER_TOKEN} は Claude Code が接続時に読み取る参照として保持されます。

claude mcp add --transport http --scope user bills https://bills.jirawat.dev/mcp \
  --header 'Authorization: Bearer ${BILL_TRACKER_TOKEN}'

CI で claude -p を使う場合は、次のようなファイルを --mcp-config で渡します。

{
  "mcpServers": {
    "bills": {
      "type": "http",
      "url": "https://bills.jirawat.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${BILL_TRACKER_TOKEN}"
      }
    }
  }
}

Codex の場合、~/.codex/config.toml に設定します（または codex mcp add bills --url https://bills.jirawat.dev/mcp --bearer-token-env-var BILL_TRACKER_TOKEN を実行します）。

[mcp_servers.bills]
url = "https://bills.jirawat.dev/mcp"
bearer_token_env_var = "BILL_TRACKER_TOKEN"

Cursor の場合、mcp.json に設定します。

{
  "mcpServers": {
    "bills": {
      "url": "https://bills.jirawat.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BILL_TRACKER_TOKEN}"
      }
    }
  }
}

VS Code の場合、.vscode/mcp.json に設定します。VS Code はトークンを一度だけ尋ね、安全に保存します。

{
  "inputs": [
    {
      "type": "promptString",
      "id": "bill-tracker-token",
      "description": "Bill Tracker personal access token",
      "password": true
    }
  ],
  "servers": {
    "bills": {
      "type": "http",
      "url": "https://bills.jirawat.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${input:bill-tracker-token}"
      }
    }
  }
}

GitHub Copilot CLI の場合（シングルクォートを使うと、変数参照が保持されます）。

copilot mcp add --transport http --header 'Authorization: Bearer ${BILL_TRACKER_TOKEN}' bills https://bills.jirawat.dev/mcp

Gemini CLI と Antigravity CLI では、トークン自体を設定に保存します。

gemini mcp add --scope user --transport http --header "Authorization: Bearer $BILL_TRACKER_TOKEN" bills https://bills.jirawat.dev/mcp
agy mcp add --header "Authorization: Bearer $BILL_TRACKER_TOKEN" bills https://bills.jirawat.dev/mcp

Windsurf と Cline では、ヘッダー内の ${env:...} が展開されます。

{
  "mcpServers": {
    "bills": {
      "serverUrl": "https://bills.jirawat.dev/mcp",
      "headers": {
        "Authorization": "Bearer ${env:BILL_TRACKER_TOKEN}"
      }
    }
  }
}

Cline では、同じ headers ブロックとともに、Cline のセクションにある "type": "streamableHttp" と "url" キーを使用してください。

Zed ではヘッダー内の変数が展開されないため、トークンは設定ファイル自体に記述します。bills エントリーに "headers": { "Authorization": "Bearer <token>" } を追加してください。

mcp-remote。 トークンをプロセス一覧に表示しないようにするには、ヘッダーをファイルに記述し（1 行に Name: value を指定します。例：Authorization: Bearer <token>）、--header-file で渡してください。

{
  "mcpServers": {
    "bills": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote@latest",
        "https://bills.jirawat.dev/mcp",
        "--transport",
        "http-only",
        "--header-file",
        "/path/to/bill-tracker-headers.txt"
      ]
    }
  }
}

エージェントができること

サーバーは 30 個のツール、3 個のリソース、1 個のプロンプトを提供します。各ツールには、上記の権限のいずれかが必要です。請求書の削除、LINE の連携解除、アカウントの削除を実行するには、リクエスト内で明示的な確認が必要です（一括削除のドライランは何も削除しないため、確認は不要です）。アカウントの削除には、上記で説明した別途の承認も必要です。また、スキルはすべての場所からサインアウトする前に確認を求めます。

請求日

請求の書き込みでは、YYYY-MM-DD 形式の正確な日付を受け付けます。2400 年から 2699 年までの年は仏暦として解釈され、サーバーは変換後のグレゴリオ暦の日付を検証する前に 543 を差し引きます。たとえば、2569-10-20 は 2026-10-20 として保存され、2567-02-29 は有効なうるう日の 2024-02-29 として保存されます。2566-02-29 は、2023-02-29 が存在しないため拒否されます。この範囲外の年は変更されません。そのため、この範囲では、本来であれば遠い未来のグレゴリオ暦の年に見える日付も意図的に対象となります。

このルールが適用されるのは、アプリ、LINE／チャット、CSV インポート、または MCP 経由で書き込む場合の請求日フィールド（dueDate、paidDate、scheduleDate、nextStatementDate）のみです。クエリとレポートの日付はグレゴリオ暦のままです。タイムスタンプと既存の履歴は変換されません。また、更新によって以前の値が完全に変更されない場合は、旧形式の値がそのまま保持されます。

請求

ツール	機能	権限
bills.list	バケット（すべて、未払い、期限超過、近日支払い予定、未確認、最優先、支払い済み、または今月）内の請求を一覧表示します。一度に最大 500 件を返し、さらに請求がある場合はその旨を通知します	bills:read
bills.get	ID または短い参照番号で請求を 1 件取得します	bills:read
bills.query	ステータス、支払期日、カテゴリ、支払い方法、フラグで請求を絞り込みます	bills:read
bills.search	請求名とメモを検索します	bills:read
bills.recentlyChanged	過去 N 日間に変更された請求を取得します	bills:read
bills.byRef	LINE チャットボットからの短い参照番号を請求に変換します	bills:read
bills.create	請求を追加します	bills:write
bills.update	請求を変更します	bills:write
bills.markPaid	請求を全額支払い済みにします	bills:write
bills.recordPayment	一部支払いを記録します	bills:write
bills.setAmount	金額を設定し、確認済みにします	bills:write
bills.confirm	見積もり金額を確認します	bills:write
bills.schedule	指定した日に支払う予定として請求をマークします	bills:write
bills.toggleTopPriority	請求を最優先として固定、または固定解除します	bills:write
bills.delete	請求を削除します（破壊的操作）	bills:delete
bills.bulkDelete	最大 500 件の請求を削除します。ドライランでは削除せずにプレビューできます（破壊的操作）	bills:delete

サマリーとレポート

ツール	機能	権限
summary.kpis	期限超過の件数、未払い総額、今後 7 日以内に支払期日を迎える請求の件数、最優先の件数を表示します	bills:read
summary.month	今月支払った金額と、未払い金額の平均を表示します	bills:read
summary.chatbot	LINE チャットボットのサマリーをデータとして取得します	bills:read
reports.spend	3、6、または 12 か月間の月別支出レポートを表示します	reports:read
reports.spendDigest	支出の概要を 1 段落で表示します	reports:read
reports.paidMonthlyAverage	過去 N か月間の月平均支払い額を表示します	reports:read

アカウント、LINE、チャット

ツール	機能	権限
account.export	すべてのデータをエクスポートします	account:read
account.delete	アカウントとそのすべてのデータを削除します（破壊的な操作です。別途承認が必要です）	account:delete
account.revokeSessions	すべてのデバイスでBill Trackerからサインアウトします（破壊的な操作です）	account:manage
lineLink.status	LINEが連携されているか、毎日のリマインダーが有効かどうかを確認します	line:read
lineLink.setNotifyEnabled	毎日のLINEリマインダーを有効または無効にします	account:manage
lineLink.unlink	LINEアカウントの連携を解除します。請求書はそのまま残ります（破壊的な操作です）	account:manage
chat.parseCommand	LINEチャットボットのタイ語または英語のコマンドを実行せずに解析します	chat:read
chat.run	LINEチャットボットのコマンドを実行します。データを変更するコマンドには確認が必要です	読み取りコマンドにはbills:readまたはchat:write、変更にはchat:write、削除にはbills:deleteも必要です

chat.runの読み取りコマンドは、サポートされているタイ語の別名を含む help、list、due、overdue、unconfirmed、summaryです。既存の chat:writeトークンは、bills:readなしでこれらのコマンドを実行できます。 chat:read権限は、chat.parseCommandによるコマンド解析のみを許可し、財務データへのアクセス権は付与しません。このツールには破壊的な操作の注釈が付いたままのため、読み取りコマンドの実行前にもクライアントが確認を求める場合があります。

リソースとプロンプト

名前	内容
bill://<id>	1件の請求書をJSON形式で表示します
summary://today	今日の概要
report://spend/<yyyy-mm>	指定した月までの期間の支出レポート
summarize-month prompt	1か月分の支出を要約します。monthをYYYY-MM形式で指定します

ツールが失敗した場合

ツールの呼び出しに失敗すると、isError: trueと、structuredContent.errorに含まれる固定コードが付いたツール結果が返されます。これにより、エージェントは問題の内容を確認して修正できます。たとえば、次のとおりです。

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "No bill with that id."
    }
  ],
  "structuredContent": {
    "error": {
      "code": 1001,
      "kind": "not-found",
      "message": "No bill with that id."
    }
  }
}

コード	種類	意味
-32602	invalid-params	引数がツールの入力スキーマと一致しません
1001	not-found	該当する請求書が存在しないか、別のアカウントに属しています
1002	invalid-bill	請求書の値が拒否されました。たとえば、スケジュール日が設定されていない定期請求書などです
1003	forbidden	データが別のアカウントに属しています
1004	confirm-required	確認なしで破壊的な操作が呼び出されました
1005	rate-limited	短時間にリクエストが多すぎます
1006	upstream-firestore	Bill Trackerのデータベースで一時的な問題が発生しました
1007	insufficient-scope	付与されていない権限が必要です

プロトコルレベルのエラーは、代わりにJSON-RPCエラーとして返されます。サーバーに存在しないツール名には-32602、内部エラー（メッセージに短い参照情報が含まれます）には-32603、サポートされていないプロトコルバージョンには-32022が返されます。

ツールの変更と非推奨化

一部のホスト（ChatGPTなど）は、管理者が更新するまでプラグインの追加時に表示されたツール一覧を使い続けるため、サーバーはツールをバージョン管理された公開仕様として扱います。

• 新しいツール、新しい任意入力、新しい任意出力フィールド、新しいエラーコードはいつでも追加される可能性があります。既存の設定は引き続き動作します。
• ツールの名前を変更したり、削除したり、既存の仕様を厳しくしたりすることはありません。サーバーは新しいツールを古いツールと並べて追加し、古いツールに非推奨の通知を付けます。ここで非推奨期間全体にわたって告知した後にのみ、古いツールを削除します。

現在、非推奨のツールはありません。今後非推奨化されるツールについては、対象のツール、代替ツール、削除日をここに記載します。

トラブルシューティング

サインインウィンドウが開きません。 クライアントからサインイン URL をコピーして、ブラウザーに貼り付けてください。リモートマシンでは、claude mcp login bills --no-browser または codex mcp login bills --no-browser を使い、リダイレクト URL を貼り付けて戻してください。Gemini CLI でのサインインにはローカルブラウザーが必要です。その場合は代わりに パーソナルアクセストークンを使用してください。

サーバーに「needs authentication」または 401 Unauthorized と表示されます。 再度サインインしてください。Claude Code では /mcp、codex mcp login bills、Gemini CLI または Copilot CLI では /mcp auth bills、Cline と Antigravity では Authenticate を使います。セッションの有効期限が切れたか、Connected AI agents で取り消された可能性があります。パーソナルアクセストークンを使用している場合は、ヘッダーが引用符や末尾の空白を含まない正確な Authorization: Bearer <token> であること、トークンの有効期限が切れていないこと、クライアントの起動時に環境変数が設定されていることを確認してください。

ツールで insufficient_scope、エラー 1007、または「needs additional permissions」が表示されます。 エージェントには、まだ許可していない権限が必要です。クライアントから求められたら承認するか、サーバーに再度サインインしてください。Claude Code では /mcp を開き、サーバーを再認証してください。パーソナルアクセストークンの場合は、その権限を含む新しいトークンを作成してください。不足している権限が account:delete の場合は、代わりに Connected AI agents ページで承認してください。クライアントはサインイン中にこの権限を要求できません。

約 1 時間ごとに再度サインインする必要があります。 クライアントが offline_access を要求しなかったため、セッションを更新できません。サーバーに再度サインインしてください。Codex では、--scopes に offline_access を含めてください。

Claude Code に「url」は表示されますが、「type」がないサーバーが報告されます。 サーバーエントリーに "type": "http" を追加してください。

Cline が接続に失敗するか、SSE にフォールバックします。 サーバーエントリーに "type": "streamableHttp" を設定してください。

ブラウザーでサーバー URL を開くと 405 Method Not Allowed と表示されます。 これは想定どおりです。このエンドポイントは POST で送信された MCP リクエストのみを受け付けます。

クライアントに未サポートのプロトコルバージョン（-32022）が表示されるか、初期化できません。 サーバーは MCP 2025-11-25 と 2025-06-18 をサポートしています。別のリビジョンを指定した initialize に対しては、2025-11-25 で応答します。続行できるかどうかはクライアントが判断します。エラー -32022 は、未サポートの MCP-Protocol-Version ヘッダーを使ったリクエストを意味します。サポート対象のリビジョンを使用できない場合は、クライアントを更新してください。2025-03-26 以前にしか対応していないクライアントは接続できない場合があります。mcp-remote はクライアント自身のハンドシェイクをそのまま転送します。

エージェントに短い参照情報を含むエラー -32603 が報告されます。 これはサーバー内部のエラーであり、セットアップの問題ではありません。しばらくしてから再試行してください。問題が続く場合は、このリポジトリで issue を作成し、参照情報を記載してください。

ツールが見つからない、または古い状態です。 サーバーはツールリストの変更をプッシュしないため、クライアントを再起動するか、サーバーを更新してください。VS Code では MCP: Reset Cached Tools、Windsurf では更新ボタンを使います。ChatGPT はプラグインの作成時点のツールのスナップショットを保持します。既存のツールは引き続き動作します（ツールの変更と非推奨化を参照）。新しいツールを取り込むには、ワークスペース管理者がプラグインの設定からスナップショットを更新してください。

すべてのツールが 2 回ずつ表示されます。 プラグインをインストールしたうえで、サーバーも手動で追加しています。どちらか一方を削除してください。

Zed が ${MY_TOKEN} をそのまま送信します。 Zed はヘッダー内の環境変数を展開しません。トークン自体を貼り付けるか、ヘッダーを削除して OAuth を使用してください。

クライアント登録またはリダイレクトのエラーでサインインに失敗します。 たとえばコネクターの詳細設定などに入力した OAuth クライアント ID またはシークレットを削除して、クライアント自身が登録できるようにしてから再試行してください。

Antigravity でサインインできますが、ツール呼び出しで 401 が返されます。 agy を更新してください。初期のバージョンでは MCP リクエストに OAuth トークンが送信されませんでした。回避策として、パーソナルアクセストークンを使ってサーバーを追加してください。 最初からやり直してください。 サーバーまたはプラグインを削除し、保存済みのサインイン情報を消去して（Claude Code では /mcp を開いて Clear authentication を選択し、codex mcp logout bills を実行します。mcp-remote の場合は ~/.mcp-auth を削除します）、Connected AI agents で古い接続を取り消してから、もう一度セットアップしてください。

サーバーを自分で確認してください。 トークンなしでは、サーバーはサインイン検出を開始する WWW-Authenticate: Bearer resource_metadata="..." ヘッダーとともに、401 Unauthorized を返すはずです。

curl -i -X POST https://bills.jirawat.dev/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

個人用アクセストークンを指定すると、ツールの一覧が表示されるはずです。サーバーはステートレスなので、プロトコルバージョンヘッダーを含む単一のリクエストで十分です。

curl -sS https://bills.jirawat.dev/mcp \
  -H "Authorization: Bearer $BILL_TRACKER_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

対話形式で確認するには、npx @modelcontextprotocol/inspector を実行し、Streamable HTTP トランスポートを選択して https://bills.jirawat.dev/mcp に接続してください。

リポジトリの構成

.
├── .agents/plugins/marketplace.json  Codex and ChatGPT desktop marketplace
├── .claude-plugin/
│   ├── marketplace.json              Claude Code marketplace (also read by Copilot CLI and VS Code)
│   └── plugin.json                   Claude Code plugin manifest
├── .github/workflows/
│   ├── ci.yml                        Validation and link checks
│   └── publish-mcp-registry.yml      Manual publish to the MCP Registry
├── .mcp.json                         MCP server for the Claude Code plugin
├── config.json                       Server URL, app URL, repository and version
├── gemini-extension.json             Gemini CLI extension manifest
├── lychee.toml                       Link checker settings
├── mcp.json                          MCP server for the Agent Plugins format
├── mcp_config.json                   MCP server for Antigravity CLI
├── plugin.json                       Agent Plugins manifest (Codex, Cursor, VS Code, Copilot CLI, Antigravity CLI)
├── scripts/
│   ├── sync.mjs                      Copies config.json values into every file
│   └── validate.mjs                  Offline checks, run locally and in CI
├── server.json                       Official MCP Registry entry
└── skills/billing-tracker/
    ├── SKILL.md                      The agent skill
    └── references/tools.md           All 30 tools with permissions and inputs

このリポジトリのメンテナンス

サーバー URL、リポジトリ、またはバージョンの変更

複数のファイルで繰り返し使われる値（サーバー URL、Connected AI agents をホストするアプリの URL、リポジトリ、バージョン）は、config.json にのみ記載されています。そこで変更してから、次を実行してください。

node scripts/sync.mjs
node scripts/validate.mjs

sync.mjs は、ワンクリックインストールリンクを含め、値が繰り返し記載されているすべてのマニフェストとドキュメントを書き換えます。たとえば node scripts/sync.mjs --server-url https://example.com/mcp のように、新しい値を直接渡すこともできます。スクリプトの実行には Node.js 18 以降が必要で、パッケージは不要です。TOML のチェックには Python 3.11 以降も必要です。

継続的インテグレーション

.github/workflows/ci.yml は、すべてのプッシュとプルリクエストで実行され、リンクチェックは毎週実行されます。すべてのファイルが config.json と一致することを確認し、scripts/validate.mjs を実行して（JSON のフォーマット、TOML、ドキュメント内のコードブロック、スキルとツール名のルール、文体をチェック）、マニフェストを公開済みの JSON Schema に照らして検証します。また、claude plugin validate --strict、gemini extensions validate、Agent Skills のリファレンスバリデーターを実行し、lychee ですべてのリンクをチェックします。

MCP Registry への公開

server.json は、サーバーを公式 MCP Registry に io.github.jirawatp/billing-tracker として登録する内容を記述しています。公開すると、GitHub を通じてその名前空間の所有権が証明されます。サーバーが稼働したら、Actions タブから Publish to MCP Registry ワークフローを実行するか、mcp-publisher を使ってターミナルから公開してください。

mcp-publisher login github
mcp-publisher publish

レジストリは登録済みのバージョンを受け付けないため、先にバージョンを上げてください。

新しいバージョンのリリース

1. config.json の version を新しい値に設定し、node scripts/sync.mjs を実行します。
2. コミットしてから、そのコミットに vX.Y.Z のタグを付け、タグをプッシュします。

Claude Code、Codex、VS Code など、バージョンでプラグインをキャッシュするクライアントは、バージョンを変更すると変更内容を取り込みます。

サーバーに合わせてスキルを更新する

skills/billing-tracker のツール名、リソース、プロンプトは、サーバーのインテグレーション契約に準拠しており、その契約は scripts/validate.mjs にも記載されています。サーバーにツールが追加されたら、その一覧と references/tools.md、必要な箇所の SKILL.md、この README のツール表にも追加してください。サーバーでツールが非推奨になった場合は、古いツールの記載を残したまま置き換え先を追加し、非推奨期間中はツールの変更と非推奨に記録してください。サーバーは非推奨期間が終わってから古いツールを削除するため、その後はここにあるすべての一覧からも削除してください。バリデーターは、リファレンスの表とこの README に契約上のすべてのツールが記載されていること、また、どのドキュメントにも契約外のツール、リソース、プロンプトが記載されていないことを確認します。

ライセンス

MIT