Connect AI Clients (MCP)

Besides the built-in AI Assistant, BookKeep can be connected to MCP-capable AI clients (Claude Desktop, Cherry Studio, Cursor, and others), so you can ask about and record your finances in the AI tool you already use.

This page covers how to create an access key, how to configure a client, and what AI clients can and cannot do today.

Where to find it

Key management lives in the Web app:

Platform	Location
Web App	Avatar menu → Profile → Security Center → "API Keys" tab
Android App / Desktop App	No key management entry yet; create keys in the Web App

Create an access key

1. Open the "API Keys" tab and click "Create Key" in the top right
2. Enter a name so you can recognize its purpose later (for example "Claude Desktop"), up to 30 characters
3. Set Scope to "MCP Only (Recommended)"
4. Copy the full key from the dialog right after creation
5. To retrieve it later, click "Copy Key" on that row to copy the full key; click "Revoke" if it leaks or is no longer used

Key rules:

Item	Description
Limit	Up to 10 active keys per account
Scope	"MCP Only" works for AI client access and cannot call other APIs; "Full Access" is equivalent to your login token and can call all APIs
Display	The list shows the key prefix; click "Copy Key" next to it to copy the full key
Last used	The list shows the most recent use time, or "Never used"
Revoke	Revoking takes effect immediately and cannot be undone

Configure your AI client

In the client's "Add MCP server / custom connector" form, fill in:

Field	Value
Transport	Remote / Streamable HTTP (do not choose a local command / stdio)
Server URL	https://bk.minbb.cn/mcp (use your own address for self-hosted deployments)
Header	Authorization: Bearer <your key>

Some clients split the header into "name / value" fields: put Authorization in the name field and the full Bearer sk-... value in the value field.

If the client cannot set custom headers, put the key in a query parameter instead: https://bk.minbb.cn/mcp?apiKey=<your key>. The key then appears in the address bar and in the client's local records, so prefer the header whenever it is supported; revoke the key immediately if you suspect a leak.

Clients that only support a local command (stdio): those clients (some desktop apps that add servers through a config file) cannot take a remote address directly — they need a bridge program installed locally that points at the server URL above. Bridging differs from client to client, so follow that client's own documentation; this page covers clients that support remote MCP.

How to confirm it works

1. After saving, the client fetches the server bookkeep and a set of tools named like queryCashItems, getCurrentUser, getBudgetInfo
2. Ask in the client: "Which books do I have?"
3. Back in the web app's "API Keys" list, check the key's "Last used" — a fresh timestamp means the call really reached your account

If the tool list is empty, the transport is usually set to a local command, or the URL does not end with /mcp.

Treat the key like a password

The key is bound to your account, and anyone holding it can read and write your records. Never post it in chats, screenshots, or public repositories; revoke it in "API Keys" immediately if it leaks.

What AI clients can do

Everything the built-in AI Assistant can do is available in external clients:

Capability	Example questions
Record details	"How much did I spend on dining last month?" "Show expenses over 500 in September"
Period totals	"How is this month going?" "How much have I spent this year?"
Category / tag ranking	"Where did my money go?" "Which tag costs the most?"
Overview and trends	"What is my savings rate?" "Show the last 12 months of spending"
Net worth timeline	"How has my net worth changed?" "When was my highest balance?"
Health score	"What is my health score this month?" "Why is it low?"
Budgets	"How much budget is left this month?" "How is this year's budget doing?" "How much did I spend each day this month?"
Saving plans	"What is my saving plan progress?" "Which plans are completed?"
Debts	"How much debt do I have?" "How long until it is paid off?"
Books / categories / tags / notes / accounts	"Which books do I have?" "What are my account balances?"
Record an entry	"Record it: 35 for lunch, paid by WeChat"
Update / delete an entry	"Change that entry to 40" "Delete the duplicate one"

For updates and deletions, the AI looks the record up first. If the record was changed from another client in the meantime, the AI reports a conflict and asks you to query again.

These actions still happen in the app

The following are not exposed to AI clients yet — please keep using the apps:

• Creating, updating, or deleting books, categories, tags, notes, accounts, debts, budgets, and saving plans
• Adding or viewing refunds
• Analysis pages such as spending profile, large transactions, spending structure, fund flow, concentration, and savings analysis
• Data export and backup

Data and calculation notes

• Scope: the AI can only access data of the account that owns the key
• Freshness: queries read your current data; entries created, updated, or deleted by the AI are written immediately
• Amounts: totals and rankings sum the recorded amount of each entry; discounts and refunds are not part of those totals, and refund amounts are shown per entry in record details

FAQ

The client fails to connect

Check in order: the transport is "Remote / Streamable HTTP", the server URL ends with /mcp, and the key is neither revoked nor over the limit; if the client cannot set headers, use the ?apiKey= form in the URL.

The client reports unauthorized

Usually an incomplete key. Make sure the value starts with Bearer (note the space) and the key itself starts with sk- and is still active; with the query-parameter form, make sure the parameter is named apiKey.

Why can it only read, not manage categories or budgets?

AI clients currently expose only the capabilities listed above; management actions stay in the apps.

Can I use it on another computer?

Yes. The key lives on the server — enter the same connection details in the new client, and revoke keys you no longer use.

Related pages

• AI Assistant
• Security Center
• Record an Entry