MCP Server

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"
    }
  }
}

{
  "mcpServers": {
    "gobl": {
      "command": "gobl",
      "args": ["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

build

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:

Name	Type	Required	Description
`data`	string	Yes	JSON document data. Must include `$schema` and typically `$regime`.
`type`	string	No	Document type hint (e.g. `bill/invoice`). Only needed when `$schema` is not set.
`envelop`	boolean	No	Wrap the result in a GOBL envelope. Default `false`.

validate

Validate a GOBL document without modifying it. Returns OK or structured validation errors with faults.Parameters:

Name	Type	Required	Description
`data`	string	Yes	JSON document data to validate. Should be a fully built document (output from `build`).

correct

Create corrective documents (credit notes, debit notes) from an existing invoice. Can also return the available correction options schema for a given document.Parameters:

Name	Type	Required	Description
`data`	string	Yes	JSON document data of the original invoice.
`options`	string	No	JSON correction options (e.g. stamps, reason, method).
`schema`	boolean	No	When `true`, returns available correction options instead of correcting.

replicate

Clone a GOBL document as a new template with a fresh UUID. Clears stamps and signatures from the original.Parameters:

Name	Type	Required	Description
`data`	string	Yes	JSON document data to replicate.

Reference Data

schema

Look up the JSON Schema definition for any GOBL type.Parameters:

Name	Type	Required	Description
`path`	string	Yes	Schema path (e.g. `bill/invoice`, `org/party`, `pay/instructions`).

regime

Get the full tax regime definition for a country. Returns tax categories, rates, extensions, scenarios, and correction definitions.Parameters:

Name	Type	Required	Description
`code`	string	Yes	Country code (e.g. `ES`, `DE`, `MX`, `GB`).

regime_list

List all available tax regimes with their country codes, names, and currencies. No parameters required.

addon

Get the full addon definition for a given key. Returns extensions, scenarios, and validation rules that the addon applies.Parameters:

Name	Type	Required	Description
`key`	string	Yes	Addon key (e.g. `es-verifactu-v1`, `mx-cfdi-v4`).

addon_list

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:

URI	Description
`gobl://schemas`	List all registered GOBL schema types
`gobl://schemas/{path}`	JSON Schema definition for a specific type
`gobl://regimes`	List all available tax regimes
`gobl://regimes/{code}`	Tax regime definition by country code
`gobl://addons`	List 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:

Call regime with code ES to look up Spanish tax rules
Call addon with key es-verifactu-v1 to check Verifactu requirements
Call build with the assembled invoice JSON to calculate totals and validate
Return the complete, calculated invoice ready for processing

Overview

Documents

Signing

Reference

Meta

Connection Options

Hosted (Streamable HTTP)

Local (Stdio)

Configuration

Claude Desktop

Claude Code

Cursor

Tools

Document Operations

Reference Data

Resources

Example Conversation

​Connection Options

​Hosted (Streamable HTTP)

​Local (Stdio)

​Configuration

​Claude Desktop

​Claude Code

​Cursor

​Tools

​Document Operations

​Reference Data

​Resources

​Example Conversation

Connection Options

Hosted (Streamable HTTP)

Local (Stdio)

Configuration

Claude Desktop

Claude Code

Cursor

Tools

Document Operations

Reference Data

Resources

Example Conversation