billing-tracker-agent-plugins

# Bill Tracker agent plugins

[![CI](https://github.com/jirawatp/billing-tracker-agent-plugins/actions/workflows/ci.yml/badge.svg)](https://github.com/jirawatp/billing-tracker-agent-plugins/actions/workflows/ci.yml)

Connect your AI agent to [Bill Tracker](https://bills.jirawat.dev), a personal
bill tracker with LINE reminders. Once connected, your agent can tell you what
is due or overdue, record payments, add and edit bills, and summarize your
spending, all through your own Bill Tracker account.

This repository holds the plugins, connector settings and agent skill. They all
point at one remote MCP server:

```text
https://bills.jirawat.dev/mcp
```

> [!NOTE]
> The Bill Tracker MCP server was deployed on 20 October 2026. Public metadata
> and the OAuth sign-in challenge have passed the deployment smoke check.
> Google sign-in and 21 live OAuth/MCP checks passed with the official JavaScript
> SDK, including bill writes, refresh and revocation. The user also verified
> LINE QR sign-in in the browser and reached the bill ledger. The individual
> client setups below still need their own live compatibility checks.

## Contents

- [What is in this repository](#what-is-in-this-repository)
- [Before you start](#before-you-start)
- [Sign-in, permissions and privacy](#sign-in-permissions-and-privacy)
- [Choose your client](#choose-your-client)
- [Install](#install)
- [Headless agents: personal access tokens](#headless-agents-personal-access-tokens)
- [What your agent can do](#what-your-agent-can-do)
- [Tool changes and deprecations](#tool-changes-and-deprecations)
- [Troubleshooting](#troubleshooting)
- [Repository layout](#repository-layout)
- [Maintaining this repository](#maintaining-this-repository)
- [License](#license)

## What is in this repository

- **One plugin** that bundles the MCP server and the `billing-tracker` agent
  skill. It installs natively in Claude Code, Codex and the ChatGPT desktop
  app, Cursor, VS Code, GitHub Copilot CLI, Gemini CLI and Antigravity CLI.
- **Plugin marketplaces**, so Claude Code, GitHub Copilot CLI, VS Code and Codex
  can add this repository as a marketplace and keep the plugin updated.
- **A `server.json`** for the official MCP Registry.
- **Copy-paste settings** for clients that connect to MCP servers directly:
  Claude apps, ChatGPT, Windsurf, Cline, Zed and stdio-only clients.
- **A portable [Agent Skill](https://agentskills.io/specification)** that
  teaches agents to use the bill tools well: common tasks, confirming before
  destructive changes, and handling dates and Thai Baht amounts.

Every configuration names the server `bills`.

## Before you start

- **A Bill Tracker account.** Sign in once at
  [Bill Tracker](https://bills.jirawat.dev) with Google or LINE to create one.
- **An MCP client that supports remote servers.** The server uses the
  Streamable HTTP transport with OAuth sign-in. Every client below supports
  that; clients that can only start local (stdio) servers can use the
  [mcp-remote bridge](#other-clients-stdio-only).
- **A current client.** The server speaks MCP protocol revisions `2025-11-25`
  (preferred) and `2025-06-18` through the standard `initialize` handshake that
  current clients use. If a client offers another revision in `initialize`,
  the server answers with `2025-11-25`; the client decides whether it can
  continue. Other requests with an unsupported `MCP-Protocol-Version` header
  get error `-32022`. The server uses Streamable HTTP only, without the legacy
  HTTP+SSE transport, so clients limited to `2025-03-26` or older may not connect.

## Sign-in, permissions and privacy

- **You sign in with your own account.** The first time your agent connects, a
  browser window opens on the Bill Tracker site. Sign in with the same Google
  or LINE account you use in the app, then review the consent screen, which shows
  the agent's name and the permissions it asks for. You never need a client ID,
  secret or API key: clients discover the sign-in flow on their own through
  standard MCP authorization (OAuth 2.1 with PKCE, client registration through
  Client ID Metadata Documents or Dynamic Client Registration).
- **You only see your own bills.** Every request runs as the account that
  signed in. An agent connected to your account cannot reach anyone else's
  bills.
- **Permissions are granted step by step.** By default the first sign-in asks
  for `bills:read`, `bills:write` and `offline_access`, which lets your client
  renew the session without another browser sign-in. Some clients, such as
  Codex, ask for every advertised permission up front. When the agent first
  uses a tool that needs more, the server asks for that permission and your
  client either reopens the consent screen or asks you to sign in to the server
  again.
- **Deleting your account always takes a separate approval.** No client can
  request the `account:delete` permission during sign-in. If you ask an agent
  to delete your account, its first attempt is refused; you then open
  [Settings > Connected AI agents](https://bills.jirawat.dev/settings/connected-agents)
  and approve the deletion on its own consent screen after a recent sign-in.
  The permission expires at that original sign-in time plus five minutes;
  approval and code exchange do not restart the clock. No refresh token is issued.
- **You can disconnect any agent.** Open
  [Settings > Connected AI agents](https://bills.jirawat.dev/settings/connected-agents)
  in Bill Tracker to see every connected agent and personal access token, and
  revoke any of them. Signing out of Bill Tracker on all devices does not
  disconnect agents; revoke them on that page.
- **Destructive actions need confirmation.** The server refuses to delete
  bills, unlink LINE or delete your account unless the request carries an
  explicit confirmation, and the included skill tells agents to ask you first.
- **This repository holds no data and no secrets.** It contains only
  configuration and instructions. Your MCP client stores your sign-in tokens,
  and your bills stay in Bill Tracker.

Read the service's [Privacy Policy](https://bills.jirawat.dev/privacy) and
[Terms of Service](https://bills.jirawat.dev/terms) before connecting a client.

| Permission | Lets the agent |
| --- | --- |
| `bills:read` | List, search and read bills and summaries, including the read commands of `chat.run` |
| `bills:write` | Add and edit bills, record payments, confirm amounts, schedule payments |
| `bills:delete` | Delete bills |
| `reports:read` | Read spending reports |
| `account:read` | Export all of your data |
| `account:manage` | Sign you out on every device, turn LINE reminders on or off, unlink LINE |
| `account:delete` | Delete your Bill Tracker account. Approved separately after a recent sign-in; expires at that sign-in plus five minutes, with no refresh |
| `line:read` | See whether LINE is linked and reminders are on |
| `chat:read` | Parse LINE chatbot commands without running them or reading bills |
| `chat:write` | Run any LINE chatbot command, including commands that only read data; deleting also needs `bills:delete` |
| `offline_access` | Stay signed in: renew the session without another browser sign-in |

## Choose your client

| Client | Recommended setup | Includes the skill |
| --- | --- | --- |
| [Claude Code](#claude-code) | Plugin from this marketplace | Yes |
| [Claude apps](#claude-apps-claudeai-claude-desktop-mobile) (claude.ai, Claude Desktop, mobile) | Custom connector | Upload it separately |
| [ChatGPT](#chatgpt) (Business, Enterprise and Edu, on the web) | Custom MCP server, created as a plugin | No |
| [Codex](#codex-cli-ide-extension-and-chatgpt-desktop-app) (CLI, IDE extension, ChatGPT desktop app) | Plugin from this marketplace | Yes |
| [Cursor](#cursor) | One-click install link, or local plugin | With the plugin |
| [VS Code and GitHub Copilot](#vs-code-and-github-copilot) | One-click install link, or plugin from source | With the plugin |
| [GitHub Copilot CLI](#github-copilot-cli) | Plugin from this marketplace | Yes |
| [Gemini CLI](#gemini-cli) | Extension | Yes |
| [Antigravity CLI](#antigravity-cli) | Plugin | Yes |
| [Windsurf](#windsurf) | `mcp_config.json` entry | No |
| [Cline](#cline) | Remote server | No |
| [Zed](#zed) | `context_servers` entry | No |
| [Stdio-only clients](#other-clients-stdio-only) | `mcp-remote` bridge | No |

Any agent that supports Agent Skills can add the skill on its own; see
[Skill only](#skill-only). Use one setup per client: installing the plugin and
also adding the server by hand gives you every tool twice.

## Install

### Claude Code

Install the plugin, which adds the MCP server and the skill. Inside Claude
Code:

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

Or from a terminal:

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

Then run `/reload-plugins` (or restart Claude Code), open `/mcp`, select
`plugin:billing-tracker:bills` and choose Authenticate.

To add only the server, for every project:

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

On a machine without a browser, `claude mcp login bills --no-browser` prints
the sign-in URL and asks you to paste the redirect URL back.

If a tool later fails with "needs additional permissions", open `/mcp` and
authenticate the server again to approve the extra permission.

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

Add Bill Tracker as a custom connector. Custom connectors are available on the
Free (one custom connector), Pro, Max, Team and Enterprise plans, and once added
they work in claude.ai, Claude Desktop, Cowork and the mobile apps.

1. Go to **Customize > Connectors**, select **+ Add**, then
   **Add custom connector**.
2. Enter the name `Bill Tracker` and the URL `https://bills.j