A Model Context Protocol server for ParserBee. It lets an AI assistant extract structured data from invoices, receipts, purchase orders, bank statements and other documents, using your Parser Templates.
Ask your assistant things like:
"Extract the invoice in ~/Downloads/inv-2041.pdf with my Invoice template."
"Read every receipt in this folder and give me a table of merchant, date and total."
"How many ParserBee page credits do I have left?"
Tool | What it does |
| Extract data from a local file ( |
| List the Parser Templates in your account, with their fields |
| One Parser Template with all of its fields |
| Page credit balance, plan and subscription status |
| The last 10 extraction requests |
| One extraction request, with its extracted data |
Related MCP server: document-to-json-mcp
Create a free account at app.parserbee.com. New accounts get 25 free pages, no credit card.
Create a Parser Template: upload one sample document and the AI builds the fields for you, or pick a ready-made one from the template library.
Copy your API key from Settings in the dashboard. It starts with pk_.
You need Node.js 18 or later.
Open Settings > Developer > Edit Config and add:
{
"mcpServers": {
"parserbee": {
"command": "npx",
"args": ["-y", "parserbee-mcp"],
"env": { "PARSERBEE_API_KEY": "pk_your_api_key" }
}
}
}Restart Claude Desktop.
claude mcp add parserbee --scope user -e PARSERBEE_API_KEY=pk_your_api_key -- npx -y parserbee-mcp--scope user makes ParserBee available in every folder. Without it, Claude Code adds the server only to the folder you run the command in. Start a new Claude Code session afterwards, then check it with claude mcp list.
Add the same mcpServers block to ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project).
Add to .vscode/mcp.json:
{
"servers": {
"parserbee": {
"command": "npx",
"args": ["-y", "parserbee-mcp"],
"env": { "PARSERBEE_API_KEY": "pk_your_api_key" }
}
}
}git clone https://github.com/ParserBee/parserbee-mcp.git
cd parserbee-mcp
npm install
PARSERBEE_API_KEY=pk_your_api_key node dist/index.jsPoint your client at node /path/to/parserbee-mcp/dist/index.js.
Environment variable | Required | Use |
| Yes | Your API key from Settings |
| No | Defaults to |
extract_document returns the API response. The extracted fields are in data, shaped like your Parser Template:
{
"success": true,
"request_id": "req_abc123",
"data": {
"invoice_number": "INV-2026-001",
"vendor_name": "Acme Corp",
"total_amount": 1500
},
"credits_remaining": 449,
"usage": { "pages_processed": 1, "credits_charged": 1 }
}Files can be PDF, PNG, JPG, WebP or HEIC, up to 50 MB. Scans and phone photos work. API errors (an invalid key, no page credits left, an unknown template) come back as tool errors with the ParserBee error code, so the assistant can tell you what to fix.
The sample-invoices repository has 18 free test invoices with the correct value of every field, so you can check the results.
parserbee-python and parserbee-node: client libraries
parserbee-n8n: n8n workflows
parserbee-postman: Postman collection and OpenAPI file
Free browser tools: invoice parser, bank statement converter, receipt scanner
Comparing tools? See our test of invoice OCR software.
npm install
npm test
npm run buildMIT
Extract structured data from an invoice, receipt, purchase order, bank statement or other document with a ParserBee Parser Template. Give either file_path (a PDF or image on this computer) or file_url (a public link). Returns the extracted fields in data. Costs 1 ParserBee page credit per page. Use list_templates to find the template_id.
| Name | Required | Description | Default |
|---|---|---|---|
| file_url | No | Public URL of the document (must open without a login) | |
| file_path | No | Absolute path to a local PDF, PNG, JPG, WebP or HEIC file | |
| template_id | Yes | ID of the Parser Template to use |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations only say readOnlyHint=false and openWorldHint=true, so the description adds real value: it discloses the billing model (1 ParserBee page credit per page) and where results land (`data`). It does not cover failure behavior, page limits, or how multi-page documents are billed beyond the per-page statement.
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?
Four compact sentences, front-loaded with purpose, then input modes, then return location, then cost and prerequisite. No sentence is filler and the ordering matches how an agent needs the information.
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?
With no output schema, the description usefully states the result is in `data`, and it covers cost and the template_id prerequisite. It omits error/failure handling and async-vs-sync behavior, which are the only notable gaps for a document-processing tool of this complexity.
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 schema already documents all three parameters and the baseline is 3. The description does add one thing the schema does not enforce: the either/or constraint between file_path and file_url, since neither is marked required. That is marginal added meaning over the schema.
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?
States a specific verb (extract) and resource (structured data from documents) and narrows the domain to invoices, receipts, purchase orders, bank statements. It also names the mechanism (ParserBee Parser Template) and the required sibling artifact (template_id), so it is clearly distinguishable from the other ParserBee tools.
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?
Gives explicit input-mode selection (either file_path for local PDF/image or file_url for a public link) and routes the agent to list_templates to obtain template_id. It stops short of stating when-not to use this tool or what to do for unsupported documents, so it is clear context without full exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the ParserBee page credit balance, plan and subscription status.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already establishes this as a safe read, so the description need not restate safety. It adds only a light behavioral signal by enumerating the data returned (balance, plan, subscription status), but says nothing about auth requirements, rate limits, or freshness of the balance.
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?
A single front-loaded sentence that names the resource first and then the returned fields. No filler, 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?
For a zero-parameter read-only tool with no output schema, the description doubles as a return-value summary by listing balance, plan, and subscription status. That is sufficient for correct invocation; only auth/scope context is missing.
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?
The tool takes zero parameters, so the schema has nothing to document and the baseline is 4. The description correctly implies no input is required.
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?
States a specific verb (Get) and a precise resource (ParserBee page credit balance, plan and subscription status). It is clearly distinct from the sibling tools (templates, extractions), though it does not explicitly name or contrast with them.
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?
There is no explicit when-to-use or when-not-to-use guidance, and no alternatives are named. However, the purpose is self-evident enough that usage is implied: call it to check account credits. With no competing sibling for the same resource, the gap is modest.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one extraction request, including the extracted data.
| Name | Required | Description | Default |
|---|---|---|---|
| request_id | Yes | ID of the extraction request |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already establishes this is a safe read. The description adds useful context that the response includes the extracted data, but says nothing about what happens for an unknown or expired request_id, nor about auth or rate limits.
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?
A single short sentence with no filler, and the key differentiator ('one') is front-loaded. It is efficient, though the brevity leaves no room for routing guidance.
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 one-parameter read tool with full schema coverage, the description is minimally adequate and does note the payload content. It omits error/not-found behavior and any routing against the closely related list_recent_extractions sibling.
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% for the single request_id parameter, so the schema already carries the parameter documentation. The description adds no format, sourcing, or constraint detail beyond that, so the baseline of 3 applies.
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 names a specific verb ('Get'), a specific resource ('one extraction request'), and clarifies the return payload ('including the extracted data'). The word 'one' implicitly distinguishes it from the sibling list_recent_extractions, though the sibling is not named.
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?
There is no explicit when-to-use guidance, no statement of prerequisites, and no reference to the alternatives such as list_recent_extractions or extract_document. The agent must infer that this tool is for fetching a single already-created request by ID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one Parser Template with all of its fields.
| Name | Required | Description | Default |
|---|---|---|---|
| template_id | Yes | ID of the Parser Template |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already tells the agent this is a safe, non-mutating read, so the safety burden is covered. The only added context is that all fields are returned ('with all of its fields'), which is minor and says nothing about failure behavior for unknown IDs.
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?
A single short sentence with no filler and the resource front-loaded. It is appropriately sized, though it is arguably too terse to be fully helpful rather than optimally concise.
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?
No output schema exists, and the description partially compensates by indicating the full record is returned. For a one-parameter read tool this is close to sufficient, missing only error/not-found behavior.
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% with a single documented template_id, so the schema carries the parameter meaning. The description adds nothing beyond restating that one template is fetched; baseline 3 applies.
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?
States a specific verb+resource (Get a Parser Template) and the scope of the fetch (one, with all fields). This implicitly separates it from list_templates, but it never names or explicitly contrasts that sibling, so an agent has to infer the boundary.
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 word 'one' implies single-item retrieval by ID versus the bulk list_templates, giving implied usage. However, there is no explicit when-to-use statement, no mention of the required template_id prerequisite, and no named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the last 10 extraction requests (status, file name, template, time).
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already declares the safety profile, so the bar is lower. The description does add real context beyond annotations: the fixed limit of 10 and the fields returned (status, file name, template, time). It stops short of covering pagination, ordering, or auth, which is acceptable for a capped list.
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?
A single compact sentence that front-loads the verb, resource and cap, then parenthetically enumerates the payload. No filler, nothing an agent must read past.
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?
With no output schema, the parenthetical field list usefully compensates by telling the agent what comes back, and the 10-item cap sets expectations. For a zero-param read-only tool this is nearly complete; only ordering/pagination nuance is left implicit, which is marginal given the hard cap.
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?
The tool takes zero parameters, so the baseline is 4. There is nothing parameter-wise for the description to explain, and the listed return fields are informative without being a substitute for schema documentation.
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?
Specific verb (List) plus resource (extraction requests) and an explicit scope (last 10), with the returned fields enumerated. It is distinct from get_extraction (single item) and extract_document (the action), but it never names a sibling to sharpen the distinction.
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 word "recent" and the cap of 10 imply the tool is for scanning extraction history, but there is no explicit statement of when to use this versus get_extraction or extract_document, and no exclusions. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the Parser Templates in the ParserBee account (ID, name, description and fields). Use an ID with extract_document.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
readOnlyHint=true already establishes the safe-read profile, so the description's main added value is the scope ('in the ParserBee account') and the returned fields. It does not disclose pagination, ordering, or whether large accounts truncate results.
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 sentences with no filler; the resource and scope come first, and the extract_document handoff follows. Every clause carries information.
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?
With no output schema, the description usefully names the fields returned (ID, name, description, fields), which is what an agent needs to chain into extract_document. It stops short of noting result ordering or volume limits, but for a zero-parameter list tool this is nearly complete.
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?
The tool takes zero parameters, so there is no parameter semantics to document; the baseline for a parameterless tool is 4. The description correctly focuses on output fields instead of inventing input semantics.
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?
States a specific verb and resource ('List the Parser Templates') and even enumerates the returned fields (ID, name, description, fields), which distinguishes it from sibling get_template (single-template retrieval) without needing to name it.
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?
Adds downstream routing guidance ('Use an ID with extract_document'), telling the agent what to do with the result. It does not explicitly state when to prefer this over get_template or list_recent_extractions, so it falls short of full when/when-not coverage.
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.
v0.1.1extract_documentget_creditsget_extractionget_templatelist_recent_extractionslist_templatesScored across 6 tools
Each tool targets a distinct resource and action: listing/getting templates, extracting a document, checking credits, and listing/getting extraction records. The only potentially confusable pair (extract_document vs get_extraction) is clearly separated by the descriptions, which distinguish initiating an extraction from retrieving an existing request.
All six tools follow a consistent snake_case verb_noun pattern (list_templates, get_template, extract_document, get_credits, list_recent_extractions, get_extraction). Verbs map predictably to actions (list/get/extract).
Six tools is well within the ideal 3-15 range and each earns its place: template discovery, extraction, credit check, and extraction history/retrieval. Nothing feels redundant or missing at the count level.
The core workflow (find template, extract document, check credits, review past extractions) is fully covered. Minor gaps exist—templates are read-only (no create/update/delete), extraction history is capped at the last 10 with no pagination, and there is no retry/cancel for failed extractions—but agents can work around these via the ParserBee UI.
Extract, search and tag any document: invoices, receipts, contracts, templates. OAuth or API key.
PDF tools + invoice extraction, bank statement parsing, GST reconciliation & GSTIN validation.
Run Docparser parsers: import documents by URL or upload, check status, read parsed results.
Turn documents into structured data: parse, extract, classify, split, and fill PDF forms.
