Fiscalo MCP by usefulapi

Read and create customers, items and draft invoices in Fiscalo.

Should I use this

Quality & Safety

A
Description quality
100%
Schema completeness
89%
Naming quality
80%
Poisoning risk
100%
Permission match
100%
Protocol compliance
100%

Based on automated analysis of tool definitions and protocol compliance.

Context Cost

~2,830Tokens (tool definitions)
~1.7 KBTypical response size
Significant attention impact (2.21% of 128k context)

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-http

What it can do

Tool inventory

Tools (13)

🟢 Read-only🟡 Write🔴 Delete⚪ Unknown
🟢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

Rate this Server

Evidence

Recent observations

verifiedversion not recorded13 tools