# Bills AI MCP server: let an AI assistant convert bank statements to CSV and read your spending

Bills AI lets an AI assistant convert a bank statement PDF to CSV and read the statements and transactions you saved in Bills AI. Every tool is read-only; sign-in is OAuth.

Last reviewed: 2026-11-13. HTML version: https://billsai.cc/mcp

## At a glance

- Server URL: https://billsai.cc/api/mcp (streamable HTTP)
- Registry name: `cc.billsai/billsai`
- Sign-in: Sign in with OAuth 2.1 (dynamic client registration, PKCE S256): you log in to your Bills AI account and approve a consent screen. Any Bills AI account can connect, free ones included. A paid-plan API key (bai_sk_...) is also accepted as a Bearer token.
- Tools: 6, all read-only
- Server card: https://billsai.cc/.well-known/mcp/server-card.json

## Agent quickstart

1. Connect the server in your client (table below). The client discovers OAuth from the 401 challenge and `/.well-known/oauth-protected-resource/api/mcp`.
2. The human signs in to their Bills AI account and approves the consent screen.
3. For a small statement PDF, call `convert_statement_pdf` with the file as base64. For a larger one, call `create_statement_upload_url` and PUT the PDF to the returned link (`curl --data-binary @statement.pdf`); the response body is the CSV result.
4. Read saved data with `list_statements`, `list_transactions`, `get_spending_summary` and `export_transactions_csv`.
5. Check converted rows against the original statement before relying on them.

| Client | How to connect |
| --- | --- |
| Claude (claude.ai, desktop) | Add a custom connector with the URL https://billsai.cc/api/mcp and approve the Bills AI consent screen. |
| Claude Code | claude mcp add --transport http billsai https://billsai.cc/api/mcp, then /mcp to sign in. Or install the plugin: /plugin marketplace add airdropfi/billsai-claude-plugin. |
| ChatGPT | Add a custom connector (developer mode) with the URL https://billsai.cc/api/mcp; sign in when asked. |
| Cursor | Add { "mcpServers": { "billsai": { "url": "https://billsai.cc/api/mcp" } } } to ~/.cursor/mcp.json and sign in when Cursor asks. |
| Gemini CLI | gemini extensions install https://github.com/airdropfi/billsai-gemini-extension, then /mcp auth billsai. |
| Any client with API-key headers | Send Authorization: Bearer bai_sk_... to https://billsai.cc/api/mcp (paid plans; each call uses API credits of the plan). |

## Tools

| Tool | What it does | Read-only |
| --- | --- | --- |
| `convert_statement_pdf` | Converts a text-layer bank statement PDF, supplied as a ChatGPT file attachment or as base64, into CSV holding the transaction table as printed on the statement. Returns the CSV text, column headers, row count, extraction method and warnings about skipped lines. The PDF is read in memory and is not stored. Scanned or photographed PDFs are not supported because no text recognition is applied, and password-protected PDFs are refused. Accepts attachments up to 10 MB and base64 up to 2 MB decoded. | Yes |
| `create_statement_upload_url` | Creates a one-time upload link, valid for 10 minutes, for a bank statement PDF of up to 10 MB. A PUT request with the PDF as the body to that link answers with the same CSV result as base64 conversion, so the file does not pass through the conversation. Suited to environments that can run an HTTP client. The PDF is read in memory and is not stored. | Yes |
| `list_statements` | Lists the bank statements saved in the signed-in Bills AI account: statement id, bank name, statement date, processing status, number of transactions and the financial health grade. File names are not included. Read-only. | Yes |
| `list_transactions` | Returns saved transactions from the signed-in Bills AI account, newest first, with date, description, signed amount, debit or credit type, category and whether the spending is marked necessary. Filters narrow by statement, year, month, category or a text search, and results are paged. Read-only. | Yes |
| `get_spending_summary` | Summarises saved transactions for a year, a month or all time: total income, total expenses, necessary and unnecessary spending, and the amount and number of transactions per category. Refunded transactions are excluded. Amounts are in the currencies of the statements, without conversion. Read-only. | Yes |
| `export_transactions_csv` | Exports saved transactions from the signed-in Bills AI account as CSV text, using the same filters as the transaction listing. Returns up to 1,000 rows per page together with the total row count. Text cells that begin with a formula character are prefixed with an apostrophe so spreadsheet apps treat them as text. Read-only. | Yes |

## How your statement and data are handled

- Converting a PDF (convert_statement_pdf, or the one-time upload link): the PDF is read in memory to extract the transaction table and the CSV goes back to the connected assistant. Nothing is saved to the Bills AI database or a file store, and our code does not log file names or contents. Only the outcome and row count of a conversion are counted.
- Saved data (list_statements, list_transactions, get_spending_summary, export_transactions_csv): these read what you already saved in Bills AI. Transactions are kept until you delete them; original descriptions and account numbers are encrypted at rest (AES-256-GCM) with keys held by Bills AI, so this is not end-to-end encryption.
- Everything a tool returns is visible to the AI assistant you connected and is handled under that provider's own terms.
- The server only reads. It cannot add, edit or delete statements, transactions or settings.
- The OAuth connection is a read-only token stored hashed, named after the app, valid 90 days. You can disconnect it in Settings > Connected AI apps.

Full details: https://billsai.cc/privacy

## Human oversight

- You approve the connection on a consent screen that lists what the app can do, before any token exists.
- Every tool is read-only, so there is nothing to approve per action and nothing that changes your data.
- You can see each connected app, when it was last used and when it expires, and disconnect it at any time in Settings > Connected AI apps.
- Your assistant's own tool-call confirmation setting applies on top; that is controlled by the assistant, not by Bills AI.

## Limits

- Text-layer PDFs only: scanned or photographed statements are not supported (no text recognition), and password-protected PDFs are refused.
- Values are copied as printed on the statement: dates and amounts are not normalised. Check rows against the original statement.
- Base64 conversion takes PDFs up to 2 MB; the one-time upload link takes up to 10 MB and is valid for 10 minutes, once.
- Conversions: 10 a minute and 40 a day per account. All other calls: 120 a minute.
- A tool result holds at most about 100,000 characters of converted CSV; the upload link returns every row.
- Statement analysis and uploading to your Bills AI account happen in the web or mobile app, not through this server.

Plans and prices: https://billsai.cc/pricing (https://billsai.cc/pricing.md). Free web converter: https://billsai.cc/tools/pdf-to-csv

## Example prompts

- Convert this bank statement PDF to CSV and tell me which rows look wrong.
- List my saved Bills AI statements and how many transactions each has.
- What did I spend by category in March this year?
- Show my transactions that mention Netflix or Spotify and add up the monthly cost.
- Export my food and dining transactions for last month as CSV.

## Plugins and listings

- [Claude Code plugin](https://github.com/airdropfi/billsai-claude-plugin)
- [Cursor kit](https://github.com/airdropfi/billsai-cursor-kit)
- [Gemini CLI extension](https://github.com/airdropfi/billsai-gemini-extension)
- Official MCP Registry name: `cc.billsai/billsai`

## FAQ

### Does Bills AI store the PDF I convert through the MCP server?

No. The PDF is read in memory to extract the transaction table and the CSV is returned to the assistant. Nothing is saved to the Bills AI database or a file store, and the code does not log file names or contents. The CSV you receive is visible to the assistant you connected.

### Can the AI assistant change or delete my statements?

No. All six tools are read-only. Adding, editing and deleting statements and transactions happen in the Bills AI app, not through this server.

### Do I need a paid plan to connect?

No. Any Bills AI account can connect with OAuth. Saved statements only exist if you analysed them in the app, and the free plan analyses 1 statement. A paid-plan API key is an alternative to OAuth and uses the API credits of the plan.

### Can it read a scanned or photographed statement?

Not through the converter: it reads the text layer of a PDF and has no text recognition. Use the original PDF from your bank, one where you can select the text.

### How do I disconnect an AI assistant?

Open Settings > Connected AI apps in Bills AI and choose Disconnect. The token stops working immediately.

Bills AI is not a bank, adviser or accountant. Check extracted values against the original statement.