Fiscalo MCP by usefulapi
Read and create customers, items and draft invoices in Fiscalo.
Should I use this
Quality & Safety
Based on automated analysis of tool definitions and protocol compliance.
Context Cost
This is the approximate number of tokens consumed each time the server's tools are loaded into a model's context. Higher counts reduce the attention available for other tasks.
Install
One-Click Install
Add this to your `claude_desktop_config.json` file:
{
"mcpServers": {
"fiscalo": {
"url": "https://fiscalo.usefulapi.io/mcp"
}
}
}Remote endpoints
https://fiscalo.usefulapi.io/mcpstreamable-httpWhat it can do
Tool inventory
Tools (13)
🟢fiscalo_connection_test
Check that the API key works and show its environment (sandbox or production). Use this first. Fiscalo API: GET /connection-test.
Input Schema
{
"type": "object",
"properties": {},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢fiscalo_list_customers(name, tax_number, external_id, page, per_page)
List customers of the company behind the API key. Filter by name, tax number or your own external_id. Fiscalo API: GET /customers.
Input Schema
{
"type": "object",
"properties": {
"name": {
"description": "Filter by customer name.",
"type": "string"
},
"tax_number": {
"description": "Filter by tax number (NIF).",
"type": "string"
},
"external_id": {
"description": "Filter by your own customer id.",
"type": "string"
},
"page": {
"description": "Page number (default 1).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"per_page": {
"description": "Results per page (1 to 100).",
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢fiscalo_get_customer(customer_id)
Get one customer by its Fiscalo id. Fiscalo API: GET /customers/{id}.
Input Schema
{
"type": "object",
"properties": {
"customer_id": {
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
"description": "The customer id (from fiscalo_list_customers)."
}
},
"required": [
"customer_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴fiscalo_create_customer(name, customer_type, external_id, tax_number, vat_number_country, ...)
Create a customer (individual or company). Writes need production access on the company. Fiscalo API: POST /customers.
Input Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 255,
"description": "Full name or company name."
},
"customer_type": {
"type": "string",
"enum": [
"individual",
"company"
],
"description": "individual or company."
},
"external_id": {
"description": "Your own id for this customer (used to find it again).",
"type": "string",
"maxLength": 255
},
"tax_number": {
"description": "Tax number (NIF).",
"type": "string",
"maxLength": 255
},
"vat_number_country": {
"description": "Two-letter VAT country code.",
"type": "string",
"maxLength": 2
},
"email": {
"type": "string",
"format": "email",
"pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
},
"phone": {
"type": "string"
},
"country": {
"description": "Two-letter country code, for example PT.",
"type": "string",
"maxLength": 2
},
"address_line_1": {
"type": "string",
"maxLength": 255
},
"address_line_2": {
"type": "string",
"maxLength": 255
},
"postal_code": {
"type": "string",
"maxLength": 255
},
"city": {
"type": "string",
"maxLength": 255
}
},
"required": [
"name",
"customer_type"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢fiscalo_list_items(page, per_page)
List products and services in the catalog. Fiscalo API: GET /items.
Input Schema
{
"type": "object",
"properties": {
"page": {
"description": "Page number (default 1).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"per_page": {
"description": "Results per page (1 to 100).",
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢fiscalo_get_item(item_id)
Get one product or service by its Fiscalo id. Fiscalo API: GET /items/{id}.
Input Schema
{
"type": "object",
"properties": {
"item_id": {
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
"description": "The item id (from fiscalo_list_items)."
}
},
"required": [
"item_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴fiscalo_create_item(name, type, unit_price, tax_rate_id, sku, ...)
Create a product or service with its unit price and tax rate. Writes need production access on the company. Fiscalo API: POST /items.
Input Schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Item name shown on documents."
},
"type": {
"type": "string",
"enum": [
"product",
"service"
],
"description": "product or service."
},
"unit_price": {
"type": "number",
"minimum": 0,
"description": "Unit price, without tax."
},
"tax_rate_id": {
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
"description": "Tax rate id (from fiscalo_list_tax_rates)."
},
"sku": {
"type": "string"
},
"description": {
"type": "string"
},
"unit": {
"description": "Unit label, for example un or h.",
"type": "string"
},
"cost_price": {
"type": "number",
"minimum": 0
},
"external_id": {
"description": "Your own id for this item.",
"type": "string"
},
"tax_exemption_reason_id": {
"description": "Tax exemption reason id, when the tax rate is 0.",
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
}
},
"required": [
"name",
"type",
"unit_price",
"tax_rate_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢fiscalo_list_tax_rates(country, type, status, active_on, page, ...)
List the global tax-rate catalog (read-only). Use it to find the tax_rate_id for an item or a document line. Fiscalo API: GET /tax-rates.
Input Schema
{
"type": "object",
"properties": {
"country": {
"description": "Two-letter country code, for example PT.",
"type": "string",
"maxLength": 2
},
"type": {
"description": "Tax type filter, as the catalog names it.",
"type": "string"
},
"status": {
"description": "Status filter, for example active.",
"type": "string"
},
"active_on": {
"description": "Only rates active on this date (yyyy-mm-dd).",
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"page": {
"description": "Page number (default 1).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"per_page": {
"description": "Results per page (1 to 100).",
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢fiscalo_list_document_series(page, per_page)
List the document series of the company. A draft needs an active series (series_id). Fiscalo API: GET /document-series.
Input Schema
{
"type": "object",
"properties": {
"page": {
"description": "Page number (default 1).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"per_page": {
"description": "Results per page (1 to 100).",
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢fiscalo_list_documents(series_id, external_id, page, per_page)
List documents (invoices, credit notes, quotes and others) with their status. Fiscalo API: GET /documents.
Input Schema
{
"type": "object",
"properties": {
"series_id": {
"description": "Only documents of this series.",
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
},
"external_id": {
"description": "Find a document by your own id.",
"type": "string"
},
"page": {
"description": "Page number (default 1).",
"type": "integer",
"minimum": 1,
"maximum": 9007199254740991
},
"per_page": {
"description": "Results per page (1 to 100).",
"type": "integer",
"minimum": 1,
"maximum": 100
}
},
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🟢fiscalo_get_document(document_id)
Get one document with its lines, taxes, totals and status (draft or issued). Fiscalo API: GET /documents/{id}.
Input Schema
{
"type": "object",
"properties": {
"document_id": {
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
"description": "The document id (from fiscalo_list_documents)."
}
},
"required": [
"document_id"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴fiscalo_create_document_draft(customer_id, series_id, document_type, issue_date, due_date, ...)
Create a draft document for a customer in an active series. The draft is NOT issued: this tool cannot issue or cancel a document. Repeating the same call sends the same Idempotency-Key, so it does not create a second draft. Fiscalo API: POST /documents.
Input Schema
{
"type": "object",
"properties": {
"customer_id": {
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
"description": "Customer id (from fiscalo_list_customers or fiscalo_create_customer)."
},
"series_id": {
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
"description": "Active series id (from fiscalo_list_document_series)."
},
"document_type": {
"type": "string",
"enum": [
"invoice",
"invoice_receipt",
"simplified_invoice",
"credit_note",
"debit_note",
"receipt",
"quote",
"proforma",
"transport_document"
],
"description": "Document type."
},
"issue_date": {
"description": "Issue date (yyyy-mm-dd).",
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"due_date": {
"description": "Due date (yyyy-mm-dd).",
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$"
},
"currency": {
"description": "Currency code. The API default is EUR.",
"type": "string",
"maxLength": 3
},
"reference_document_id": {
"description": "The document this one corrects or refers to (for credit and debit notes).",
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
},
"reference_reason": {
"type": "string"
},
"external_id": {
"description": "Your own id for this document. A repeated external_id returns the existing document.",
"type": "string"
},
"notes": {
"description": "Notes printed on the document.",
"type": "string"
},
"internal_notes": {
"description": "Notes kept inside the company.",
"type": "string"
},
"idempotency_key": {
"description": "Optional Idempotency-Key. When omitted, one is derived from the request.",
"type": "string",
"minLength": 1,
"maxLength": 255
}
},
"required": [
"customer_id",
"series_id",
"document_type"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}🔴fiscalo_add_document_line(document_id, quantity, item_id, description, unit, ...)
Add a line to a draft document. Only drafts accept lines; issued documents return document_not_editable. A retry adds the line again: check the document first. Fiscalo API: POST /documents/{id}/lines.
Input Schema
{
"type": "object",
"properties": {
"document_id": {
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$",
"description": "The draft document id."
},
"quantity": {
"type": "number",
"exclusiveMinimum": 0,
"description": "Quantity (greater than 0)."
},
"item_id": {
"description": "Item id (from fiscalo_list_items). Leave out for a free-text line.",
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
},
"description": {
"type": "string"
},
"unit": {
"type": "string"
},
"unit_price": {
"description": "Unit price, without tax.",
"type": "number",
"minimum": 0
},
"discount_rate": {
"description": "Discount in percent (0 to 100).",
"type": "number",
"minimum": 0,
"maximum": 100
},
"tax_rate_id": {
"description": "Tax rate id (from fiscalo_list_tax_rates).",
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
},
"tax_exemption_reason_id": {
"type": "string",
"pattern": "^[0-9A-HJKMNP-TV-Z]{26}$"
},
"sort_order": {
"type": "integer",
"minimum": 0,
"maximum": 9007199254740991
}
},
"required": [
"document_id",
"quantity"
],
"$schema": "https://json-schema.org/draft/2020-12/schema"
}Community
Evidence