This server converts PDF bank statements into validated JSON, Excel, or CSV using MainBook, while also letting you inspect conversions, balances, and local output preferences.
Convert a PDF bank statement (local file path over stdio, HTTPS URL in remote mode) into JSON, XLSX, or CSV.
Get a conversion result later by job_id after a timeout.
List past conversion jobs with cursor pagination.
Check page-credit balance: total, reserved, and available.
Read or change the default local output folder, or reset it to next-to-source behavior.
Receive reconciliation checks: opening balance + credits − debits vs closing balance, mismatched rows, and warnings.
Works with stored MainBook login or a manual API key; remote HTTP mode returns safe download instructions instead of server-local files.
A finance MCP server scoped to one job: turning PDF bank statements into checked JSON, Excel or
CSV — not a general accounting MCP. It runs locally after one mainbook-mcp auth login, or over
MainBook's hosted endpoint at https://mcp.mainbook.ai/mcp, where your client signs you in with your
MainBook account. Existing mb_live_ API keys keep working for scripts and older clients.
Point your assistant at a statement and ask for a spreadsheet. The PDF goes to
MainBook, which extracts every transaction, normalises dates to
YYYY-MM-DD, keeps money as exact amounts, and re-adds the statement so that
opening balance + credits − debits has to match the closing balance. Rows that do not fit are
flagged instead of being passed on quietly.
> Convert ~/Downloads/march-statement.pdf and save the Excel next to it.
mainbook - convert_bank_statement (MCP)
63 transactions · 4 pages · 4 credits
Totals reconciled against the statement
Saved to ~/Downloads/march-statement.xlsx
Done — 63 transactions. Opening 4,127.50 and closing 3,881.05 both match
the statement, and nothing was flagged.It does not connect to bank accounts and is not an Open Banking or bank-data API. It reads statement files you already have. Nothing is scraped and no banking credentials are involved.
A MainBook account and the folders holding your statements. Conversion is the only tool that spends
page credits. Of the other four, get_balance and list_conversions only read, get_conversion
may write a result file, and output_folder changes a local preference; none of them changes
anything in your MainBook account.
Sign in once from a terminal:
uvx mainbook-mcp auth loginThe command opens MainBook in your browser, shows the same short code in both places, and waits for
your approval. It stores the credential in the OS keyring when the optional keyring package is
installed and working. Otherwise it uses ~/.config/mainbook/credentials.json with private
directory and file permissions. Use mainbook-mcp auth status to check the active credential
server-side without spending page credits. mainbook-mcp auth logout revokes that stored key first,
then removes the local copy; if MainBook cannot be reached, it says plainly that the key may still be
active. Signing in again revokes the previously stored key before saving its replacement. The device
token response does not include an email or account ID, so status says that account identity was not
provided instead of guessing.
Then add one entry to your client's MCP configuration. This is the same block for Claude Desktop (Settings → Developer → Edit Config), Claude Code, and Cursor; no key is copied into it:
{
"mcpServers": {
"mainbook": {
"command": "uvx",
"args": ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"]
}
}
}Codex reads TOML, so put the same thing in ~/.codex/config.toml:
[mcp_servers.mainbook]
command = "uvx"
args = ["mainbook-mcp", "~/Downloads", "~/Desktop", "~/Documents"]uvx comes with uv; install it once with brew install uv or
curl -LsSf https://astral.sh/uv/install.sh | sh. It fetches and runs the published package, so
there is nothing to download by hand and nothing to update. If you would rather not add uv, run
pip install mainbook-mcp and use "command": "mainbook-mcp" with the same arguments — you then
upgrade it yourself with pip install -U mainbook-mcp.
The folder arguments are the only places the server may read a statement from or write a result to;
anything outside them is refused. MAINBOOK_ALLOWED_DIRS sets the same list through the
environment instead, separated by the platform's os.pathsep (: on macOS/Linux, ; on Windows).
MAINBOOK_API_KEY takes precedence over any stored login. Keep the manual method for automation
where an interactive browser is not available. auth login warns when this variable will keep
overriding the newly stored credential:
export MAINBOOK_API_KEY="mb_live_REPLACE_ME"
mainbook-mcpCreate and revoke manual keys at https://mainbook.ai/developer. Never commit them.
Claude Desktop also accepts a one-file bundle: Extensions → Install Extension… and pick
mainbook.mcpb. It asks for the API key and the folders in a dialog and manages its own Python
runtime, so nothing needs installing first. The config block above does the same job and is the
better fit if you already keep other servers there. Build the bundle from this directory with:
npx --yes @anthropic-ai/mcpb@2.1.2 validate manifest.json
npx --yes @anthropic-ai/mcpb@2.1.2 pack . dist/mainbook.mcpbRelated MCP server: document-to-json-mcp
convert_bank_statement: creates a paid page-credit job, uploads one PDF, starts conversion,
polls for up to 30-900 seconds, and returns the reviewed result. JSON stays inline. In local
stdio mode, XLSX/CSV bytes are written to disk and only the full path enters model context.
get_conversion: checks a job after a timeout and returns JSON inline or writes XLSX/CSV to a
chosen local destination.
list_conversions: returns one cursor page of account jobs plus next_cursor.
get_balance: returns total, reserved, and available credits, all measured in PDF pages.
output_folder: reads or changes the default local result folder.
Local stdio mode lists all five tools. Hosted HTTP mode lists exactly the first four;
output_folder is not advertised remotely because the server's disk does not belong to the client.
There are no tools for buying credits, payments, deleting jobs, or changing account data.
Tools that can create a conversion, write a local result file, or change the output preference are
marked non-read-only. get_conversion is read-only over hosted HTTP, where it writes no file, and
non-read-only over local stdio, where it may write XLSX or CSV. None is marked destructive because
existing result files are never replaced.
For local stdio clients (Claude Desktop, Claude Code, Cursor, and Codex), XLSX and CSV results are written to the first available destination in this order:
output_path supplied to convert_bank_statement or get_conversion (an absolute filename or
an existing folder);
the folder remembered by output_folder;
next to the source PDF, with the same base name and the result extension.
get_conversion cannot infer the original PDF folder. Without output_path or a valid remembered
folder it returns a clear error instead of guessing a destination. Every successful file response
contains the absolute path and explains which rule selected it. Existing files are never replaced:
statement.xlsx is followed by statement (2).xlsx, then (3), and so on.
Ask the client to call output_folder with no argument to see the current setting and every allowed
folder. Set it with an allowed absolute directory, or pass next_to_source to restore the default.
The preference is shared by local clients on the same machine in ~/.mainbook/preferences.json.
A saved folder that is missing or no longer allowed is ignored, and that fallback is stated in the
result.
JSON remains inline. It is also written to a .json file only when an explicit output_path is
provided. In remote HTTP mode, local paths and output_folder are unavailable, because the server disk
does not belong to the client. XLSX/CSV comes back as a one-time download link that expires in
ten minutes when you signed in through OAuth, and as a REST download instruction when you
authenticated with a legacy mb_live_ key.
Python 3.11 or newer
A MainBook account
From this directory:
python3 -m venv .venv
.venv/bin/python -m pip install .To prefer the OS keyring over the private JSON fallback, install the optional extra in every environment that runs the login command or the local server:
.venv/bin/python -m pip install '.[keyring]'Use a plain install, not pip install -e .. In this checkout the editable install writes a .pth
file that the interpreter does not pick up, so python -m mainbook_mcp fails with "No module named
mainbook_mcp" while the package looks installed. An identical file under another name is honoured,
so the content is fine and the cause is still unexplained — a plain install sidesteps it entirely.
If you use the manual method for automation, keep mb_live_... values in a secret environment or
client configuration. Never commit them.
MainBook runs this server for you at https://mcp.mainbook.ai/mcp, so a client that speaks remote
MCP needs nothing installed. Paste that URL into claude.ai, Claude Desktop, ChatGPT or Cursor and
sign in with your MainBook account when the client asks; no key is copied into the configuration.
Cursor takes a fixed client id instead of registering itself, so give it this block:
{
"mcpServers": {
"mainbook": {
"url": "https://mcp.mainbook.ai/mcp",
"auth": {
"CLIENT_ID": "mainbook-cursor",
"scopes": ["mainbook:read", "mainbook:convert"]
}
}
}
}A client that cannot sign in can still send a legacy key from mainbook.ai/developer:
Authorization: Bearer mb_live_REPLACE_MEEither credential is read from each request, so every user of a client reaches their own MainBook
account and spends their own page credits. initialize and tools/list answer without a
credential; every tool call requires one. Local file paths and output_folder do not exist over HTTP — pass file_url instead
of file_path, because the server's disk is not yours. XLSX or CSV results come back as a
one-time download link (ten minutes, single use) for OAuth sessions, or as a REST download
instruction for a legacy mb_live_ key.
You can also run the same remote mode yourself. It is stateless Streamable HTTP with JSON responses:
mainbook-mcp --transport http --host 127.0.0.1 --port 8000The MCP endpoint is then http://127.0.0.1:8000/mcp. Each client should send its own header:
Authorization: Bearer mb_live_REPLACE_METhe header is read from each tool-call request and never stored in global state. Hosted HTTP mode
does not inspect MAINBOOK_API_KEY, the OS keyring, or the local credential file. For Codex remote
mode:
[mcp_servers.mainbook]
url = "https://mcp.mainbook.ai/mcp"
bearer_token_env_var = "MAINBOOK_API_KEY"
tool_timeout_sec = 920
default_tools_approval_mode = "writes"Replace the URL with your own host if you deploy this yourself; a self-hosted deployment still needs normal HTTPS termination and access controls.
Account sign-in is live on https://mcp.mainbook.ai/mcp (since 2026-08-20). The verifier stays
disabled by default in this source tree, so a deployment you run yourself has to enable it
deliberately. Wherever it is enabled, initialize and tools/list remain public, while each tool
call accepts either an existing mb_live_ key or a MainBook RS256 access token. OAuth tokens are verified locally against only the
configured MainBook JWKS URL; they are never forwarded to the Developer API. The MCP server sends a
fresh 60-second X-MainBook-Service credential for every internal REST request instead.
The hosted tool scopes are fixed in one map: convert_bank_statement requires
mainbook:convert; get_balance, get_conversion, and list_conversions require
mainbook:read. Protected-resource metadata is published at
/.well-known/oauth-protected-resource/mcp only while the flag is enabled.
MAINBOOK_API_KEY: optional in stdio and takes precedence over a stored login; ignored in HTTP
mode, where every tool call must carry its own Bearer header.
MAINBOOK_API_BASE_URL: REST host, default https://api.mainbook.ai. The server appends
/api/v1/developer.
MAINBOOK_ALLOWED_DIRS: local folders allowed for source reads and result writes, separated by the platform's
os.pathsep (: on macOS/Linux and ; on Windows). Positional directory arguments take
priority. If neither is supplied, the defaults are ~/Downloads, ~/Desktop, and
~/Documents.
MAINBOOK_MCP_TRANSPORT: stdio (default) or http.
MAINBOOK_MCP_HOST: HTTP bind host, default 127.0.0.1.
MAINBOOK_MCP_PORT: HTTP bind port, default 8000.
MAINBOOK_MCP_OAUTH_ENABLED: hosted OAuth verifier feature flag, default false. With the flag
off, metadata is absent and hosted Bearer handling remains the legacy mb_live_ behavior.
MAINBOOK_MCP_OAUTH_ISSUER: exact trusted issuer, default https://api.mainbook.ai.
MAINBOOK_MCP_OAUTH_JWKS_URL: trusted JWKS URL, default
https://api.mainbook.ai/.well-known/jwks.json. Token header URLs are ignored.
MAINBOOK_MCP_OAUTH_RESOURCE: exact audience/resource, default
https://mcp.mainbook.ai/mcp.
MAINBOOK_MCP_OAUTH_CLOCK_SKEW_SECONDS: NumericDate clock allowance, default 5.
MAINBOOK_MCP_OAUTH_MAX_TOKEN_AGE_SECONDS: maximum accepted age from iat, default 600.
MAINBOOK_MCP_OAUTH_JWKS_CACHE_TTL_SECONDS: JWKS cache lifetime, default 300.
MAINBOOK_MCP_OAUTH_JWKS_REFRESH_MIN_INTERVAL_SECONDS: minimum interval between unknown-kid
refresh attempts, default 30.
MCP_SERVICE_SIGNING_SECRETS: comma-separated service-door secrets. MCP signs with the first;
Django may accept current and previous values during rotation. Required when OAuth is enabled;
never commit it.
file_path and file_url are mutually exclusive. file_path is accepted only over local
stdio; HTTP mode rejects it before the filesystem loader runs and requires file_url.
Local file_path access and result-file writes use the same configured folders. Positional CLI directories take
priority over MAINBOOK_ALLOWED_DIRS; the environment takes priority over the defaults
~/Downloads, ~/Desktop, and ~/Documents. Every root is expanded and resolved, missing
roots are ignored, and the active roots are printed to stderr when the server starts. If no
roots remain, local access fails closed while the server continues running.
Output parents are resolved before writing and checked by directory identity, so a symlink cannot redirect a result outside the allowed folders. Result creation is exclusive and collision-safe; existing files are not overwritten.
~/.mainbook/preferences.json is replaced atomically. The .mainbook directory is mode 0700
and the preference file is mode 0600; malformed or unreadable preferences are ignored safely.
Terminal credentials use the OS keyring when the optional package is usable. The fallback
~/.config/mainbook/credentials.json is replaced atomically inside a mode 0700 directory and
is mode 0600; its top-level entries are keyed by API base URL.
Local paths are expanded and strictly resolved before the allowlist check, so .. and symlinks
cannot make an outside target appear to be inside an allowed folder. The resolved path must be
strictly below a root, not equal to the root itself.
The local file is opened once. The server uses fstat on that descriptor to require a regular
file and enforce the 50 MiB limit, then performs the bounded read through the same descriptor.
This closes the check-versus-read replacement window, but it does not fully eliminate the race
between resolving the path and opening it; the path can still be replaced during that interval.
A local file must contain %PDF- within its first 1024 bytes before pypdf is invoked. Filename
extensions are not used to decide whether a file is a PDF.
Remote files must use HTTPS. Redirects are not followed.
DNS answers are rejected if any address is private, loopback, link-local, metadata, reserved, or otherwise non-public, for IPv4 and IPv6.
URL downloads connect to an already validated numeric IP while retaining the original hostname
for TLS certificate verification and the HTTP Host header, closing DNS-rebinding races.
Content-Length and the actual streamed byte count are independently capped at 50 MiB.
PDFs are parsed locally with pypdf and capped at 500 pages.
Presigned upload headers from MainBook are forwarded unchanged; the MainBook Bearer key is never sent to storage.
.venv/bin/python -m pip install '.[dev]'
.venv/bin/pytest
.venv/bin/pytest --cov=mainbook_mcp --cov-report=term-missing --cov-report=annotate:cov_annotate
.venv/bin/ruff check .All REST tests use mocks or a local stub. No test requires or accepts a real MainBook API key.
Convert one PDF bank statement through the complete MainBook workflow: create a job, upload, start, poll, and return structured data. This creates a job and spends page credits; it is not read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| file_url | No | Public HTTPS URL of a PDF for remote mode. Redirects and non-public network addresses are rejected. Exactly one source is required. | |
| file_path | No | Path to a PDF on the MCP server machine. This field is only available over stdio and is rejected in HTTP mode; remote clients must use file_url. The path must be inside the allowed folders, which default to Downloads, Desktop, and Documents. Exactly one of file_path and file_url is required. | |
| output_path | No | Optional absolute result file or existing folder on the MCP server machine. Only available over stdio and only inside the allowed folders. The file extension is corrected to match result_type. | |
| result_type | No | JSON is returned inline. Over stdio, XLSX or CSV is written to an allowed local folder and the full path is returned. HTTP mode returns safe download instructions. Binary bytes never enter model context. | json |
| idempotency_key | No | Optional value forwarded verbatim in the Idempotency-Key REST header. | |
| timeout_seconds | No | Internal polling budget from 30 to 900 seconds. Timeout leaves the job running and returns its job_id for get_conversion. The default stays under the 60-second request timeout most MCP clients enforce; a client that gives up first discards the job_id and the conversion looks lost. |
| Name | Required | Description |
|---|---|---|
| data | No | |
| pages | Yes | |
| state | Yes | |
| job_id | Yes | |
| message | Yes | |
| download | No | |
| timed_out | No | |
| saved_file | No | |
| validation | Yes | |
| result_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=false, idempotentHint=false, destructiveHint=false, openWorldHint=true. The description adds value by explicitly stating the workflow creates a job, spends page credits, and is not read-only. It does not contradict any annotation and provides useful behavioral context beyond the boolean hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences that are front-loaded and highly efficient. The first sentence immediately conveys the action and workflow; the second adds critical behavioral context. Every word earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (multi-step workflow, 6 parameters, output schema exists), the description covers the high-level workflow and side effects. It could briefly mention that results can be inline JSON or file-based (from result_type), but the parameter descriptions and output schema fill that gap. Overall complete for an agent to understand purpose and side effects.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The overall description does not add parameter-specific meaning, but the individual parameter descriptions are already thorough. The tool description appropriately focuses on the overall workflow rather than repeating schema details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Convert one PDF bank statement' with a specific verb and resource, and outlines the complete workflow (create, upload, start, poll, return). It explicitly distinguishes itself from read-only siblings (get_balance, get_conversion) by stating 'it is not read-only' and 'spends page credits'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is the primary conversion tool and notes it is not read-only, giving clear context for use. However, it does not explicitly state when not to use it or reference alternatives like list_conversions or get_conversion for post-processing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return total, reserved, and available MainBook credits. Every value is measured in PDF pages.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| units | No | |
| balance | Yes | |
| reserved | Yes | |
| available | Yes | |
| explanation | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, indicating a read-only, externally mutable resource. The description adds clarity by specifying the exact credits (total, reserved, available) and confirming the unit (PDF pages). No contradictions found.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, dense sentences with no wasted words. The first sentence states what the tool returns, the second clarifies the measurement unit. Perfectly front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter read-only tool with an output schema, the description fully covers the purpose, items returned, and units. The output schema presumably details the structure, so no additional return-value explanation is needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and there are no parameters to document. The description provides the meaning of the return values (total, reserved, available) which is helpful, but since there are no params, a baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Return') and identifies the resource ('MainBook credits') and three precise items (total, reserved, available). It distinguishes itself from siblings like 'convert_bank_statement' or 'list_conversions' by being clearly a balance/account query tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use when an agent needs to check credit balances before performing PDF-related operations. It does not explicitly state when not to use it or name alternatives, but with 0 params and a dedicated name, its niche is obvious.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the current state of one MainBook conversion. When successful, return JSON inline or save XLSX/CSV locally over stdio. HTTP mode returns safe download instructions. Use this after convert_bank_statement times out.
| Name | Required | Description | Default |
|---|---|---|---|
| job_id | Yes | Conversion job UUID returned by MainBook. | |
| output_path | No | Optional absolute result file or existing folder on the MCP server machine. Only available over stdio and only inside the allowed folders. | |
| result_type | No | Result representation to retrieve after the job succeeds. | json |
| Name | Required | Description |
|---|---|---|
| data | No | |
| pages | Yes | |
| state | Yes | |
| job_id | Yes | |
| message | Yes | |
| download | No | |
| timed_out | No | |
| saved_file | No | |
| validation | Yes | |
| result_type | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds context beyond annotations by explaining output modes (inline JSON, local file save over stdio, HTTP download instructions). However, it does not disclose potential side effects or whether repeated polling affects the conversion state. The annotations (readOnlyHint: false, openWorldHint: true) signal uncertainty, but the description does not fully address behavioral traits like idempotency or changes to the conversion state.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is four sentences with no redundancy. The first sentence states the purpose, the next two explain behavior in different modes, and the last gives a usage hint. Every sentence adds value, and it is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (polling tool with output schema and sibling tools), the description covers output modes and when to use it, but it lacks guidance on polling frequency, lifecycle (one-time or repeatable), and failure handling. The existence of an output schema reduces the burden for return values, but more context on the polling workflow would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and each parameter has a clear description in the schema (job_id, output_path, result_type). The tool description does not add any additional parameter semantics beyond what the schema already provides. With full coverage, baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets the current state of one MainBook conversion, using a specific verb ('Get') and resource ('one MainBook conversion'). It effectively distinguishes from siblings: convert_bank_statement is the preceding step, list_conversions lists all conversions, and get_balance is unrelated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit guidance is given: 'Use this after convert_bank_statement times out.' This tells the agent exactly when to invoke this tool. While it does not explicitly state when not to use it or list alternatives beyond the sibling set, the context is clear enough for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List one cursor page of conversion jobs visible to the MainBook account. Pass the returned next_cursor to continue.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Jobs on this page, from 1 to 100. | |
| cursor | No | Opaque next_cursor from the previous page. |
| Name | Required | Description |
|---|---|---|
| count | Yes | |
| units | No | |
| conversions | Yes | |
| next_cursor | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true. The description adds behavioral context beyond that: it clarifies scope ('visible to the MainBook account') and the cursor-based pagination mechanism. This extra detail is valuable for an agent deciding how to interact with the tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero wasted words. The first sentence states the core purpose and scope; the second gives the key usage instruction for pagination. Information is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (pagination list with two parameters), full schema coverage, presence of an output schema, and comprehensive annotations, the description is complete. It does not need to explain return values (output schema covers that) and provides all necessary usage context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for both limit and cursor. The description mentions 'cursor page' and 'next_cursor,' reinforcing the cursor parameter's role but adding no new semantic detail beyond what the schema already provides. Baseline score 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List one cursor page of conversion jobs visible to the MainBook account.' It uses a specific verb ('list'), resource ('conversion jobs'), and includes scope constraints ('one cursor page', 'MainBook account'), effectively distinguishing it from sibling tools like get_conversion (single item) and convert_bank_statement (action).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description instructs the agent to 'Pass the returned next_cursor to continue,' providing clear pagination usage. It implies the tool is for listing pages of conversions but does not explicitly state when not to use it or compare to alternatives. However, given distinct siblings, the guidance is effective.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read or change the default local result folder. Call with no path to inspect the current setting and allowed folders. Pass an allowed absolute folder, or 'next_to_source' to restore the default behavior.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | Allowed absolute folder to remember, or 'next_to_source' to reset. Omit to read without changing anything. |
| Name | Required | Description |
|---|---|---|
| message | Yes | |
| output_folder | Yes | |
| allowed_folders | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already indicate idempotent and non-destructive. Description adds context about inspecting vs changing, 'allowed folders' restriction, and special 'next_to_source' value. This enriches the behavioral model beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with purpose, no filler. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one optional parameter, output schema present, and clear annotations, the description covers all needed context: read vs write, allowed folder restriction, reset behavior. No missing information for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and description aligns perfectly. Both clarify that omitting path reads, providing a path changes it, and 'next_to_source' is a special reset value. No gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Read or change the default local result folder' with specific verbs and resource. It distinguishes from siblings which deal with bank statements and balances, so no confusion.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use guidance: 'Call with no path to inspect the current setting' for read, 'Pass an allowed absolute folder, or 'next_to_source' to restore' for write. No sibling overlap requires exclusion clauses.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.5.1convert_bank_statementget_balanceget_conversionlist_conversionsoutput_folderEach tool has a clearly distinct purpose: convert_bank_statement handles submission, get_balance checks credits, list_conversions enumerates jobs, get_conversion retrieves state/results, and output_folder manages local storage. No overlap in functionality.
Tool names mostly follow a verb_noun pattern with consistent snake_case. 'convert_bank_statement', 'get_balance', 'list_conversions', and 'get_conversion' are clear. 'output_folder' is slightly less standard as a verb but still readable and consistent in style.
Five tools cover the core workflows for a PDF statement converter: submission, credit monitoring, job listing, status retrieval, and output configuration. This is well-scoped without unnecessary extras or missing essentials.
The set provides a complete lifecycle for converting statements: submit, monitor progress, retrieve results, manage output folder, and check credits. Minor gaps like cancel/delete are absent but not critical given the workflow's design.
Convert PDF bank statements into structured transactions, accounts, and balances.
Turn bank statement PDFs, CSVs, XLSX and OFX into categorised transactions plus a summary.
Turn any PDF into structured JSON via AI + OCR: invoices, bank statements, contracts.
PDF tools + invoice extraction, bank statement parsing, GST reconciliation & GSTIN validation.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/human-beyond/mainbook-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
