Skip to main content
GOBL provides an MCP (Model Context Protocol) server that exposes document building, validation, and tax reference data to AI assistants like Claude. It lets you build, validate, and explore GOBL documents through natural language conversations.

​
Connection Options

The GOBL MCP server is available in two ways:

​
Hosted (Streamable HTTP)

Connect to the hosted server at: 
https://gobl.dev/v0/mcp
This uses the Streamable HTTP transport and runs stateless — no session management required.

​
Local (Stdio)

If you have the GOBL CLI installed, launch a local MCP server over stdio: 
gobl mcp
This is useful for offline usage or when you want to use a specific GOBL version.

​
Configuration

​
Claude Desktop

Add the following to your Claude Desktop configuration (claude_desktop_config.json): 
{
  "mcpServers": {
    "gobl": {
      "type": "streamablehttp",
      "url": "https://gobl.dev/v0/mcp"
    }
  }
}

​
Claude Code

Add the GOBL MCP server to your project or user settings: 
claude mcp add gobl --transport http https://gobl.dev/v0/mcp
Or for the local stdio version: 
claude mcp add gobl -- gobl mcp

​
Cursor

Add to your Cursor MCP settings (.cursor/mcp.json): 
{
  "mcpServers": {
    "gobl": {
      "type": "streamablehttp",
      "url": "https://gobl.dev/v0/mcp"
    }
  }
}

​
Tools

The MCP server exposes 9 tools for working with GOBL documents and reference data.

​
Document Operations

Calculate and validate a GOBL document. Provide partial or complete JSON and get back a fully calculated document with totals, tax calculations, and validation.Parameters:
NameTypeRequiredDescription
datastringYesJSON document data. Must include $schema and typically $regime.
typestringNoDocument type hint (e.g. bill/invoice). Only needed when $schema is not set.
envelopbooleanNoWrap the result in a GOBL envelope. Default false.
Validate a GOBL document without modifying it. Returns OK or structured validation errors with faults.Parameters:
NameTypeRequiredDescription
datastringYesJSON document data to validate. Should be a fully built document (output from build).
Create corrective documents (credit notes, debit notes) from an existing invoice. Can also return the available correction options schema for a given document.Parameters:
NameTypeRequiredDescription
datastringYesJSON document data of the original invoice.
optionsstringNoJSON correction options (e.g. stamps, reason, method).
schemabooleanNoWhen true, returns available correction options instead of correcting.
Clone a GOBL document as a new template with a fresh UUID. Clears stamps and signatures from the original.Parameters:
NameTypeRequiredDescription
datastringYesJSON document data to replicate.

​
Reference Data

Look up the JSON Schema definition for any GOBL type.Parameters:
NameTypeRequiredDescription
pathstringYesSchema path (e.g. bill/invoice, org/party, pay/instructions).
Get the full tax regime definition for a country. Returns tax categories, rates, extensions, scenarios, and correction definitions.Parameters:
NameTypeRequiredDescription
codestringYesCountry code (e.g. ES, DE, MX, GB).
List all available tax regimes with their country codes, names, and currencies. No parameters required.
Get the full addon definition for a given key. Returns extensions, scenarios, and validation rules that the addon applies.Parameters:
NameTypeRequiredDescription
keystringYesAddon key (e.g. es-verifactu-v1, mx-cfdi-v4).
List all available addons with their keys, names, descriptions, and dependencies. No parameters required.

​
Resources

The server also exposes MCP resources for browsing reference data:
URIDescription
gobl://schemasList all registered GOBL schema types
gobl://schemas/{path}JSON Schema definition for a specific type
gobl://regimesList all available tax regimes
gobl://regimes/{code}Tax regime definition by country code
gobl://addonsList all available addons
gobl://addons/{key}Addon definition by key

​
Example Conversation

Here’s an example of what you can do with the GOBL MCP server connected to an AI assistant:
You: Create a Spanish invoice from Seller SL (B85905495) to Buyer SL (B85905495) for consulting services at 1000 EUR with standard VAT, using Verifactu.
The assistant will:
  1. Call regime with code ES to look up Spanish tax rules
  2. Call addon with key es-verifactu-v1 to check Verifactu requirements
  3. Call build with the assembled invoice JSON to calculate totals and validate
  4. Return the complete, calculated invoice ready for processing