An MCP server that connects your AI assistant to Frihet. Create invoices by talking. Query expenses in natural language. Manage your entire business from your IDE.
You: "Create an invoice for TechStart SL, 40 hours of consulting at 75 EUR/hour, due March 1st"
Claude: Done. Invoice INV-2026-089 created. Total: 3,000.00 EUR + 21% IVA = 3,630.00 EUR.
157 tools. 11 resources. 10 prompts. Structured output on every tool. Zero boilerplate.
With OAuth 2.0 + PKCE (browser-based login, no API key needed):
Clients that support OAuth (Claude Desktop, Smithery, etc.) can connect directly to https://mcp.frihet.io/mcp and authenticate via browser. The server implements the full OAuth 2.1 authorization code flow with PKCE.
"Show me all unpaid invoices"
"Create an invoice for Acme SL with 10h of consulting at 95/hour"
"Mark invoice abc123 as paid"
"How much has ClientName been invoiced this year?"
"Log a 59.99 EUR expense for Adobe Creative Cloud, category: software, tax-deductible"
"List all expenses from January"
"What did I spend on travel last quarter?"
"Add a new client: TechStart SL, NIF B12345678, email admin@techstart.es"
"Show me all my clients"
"Update ClientName's address to Calle Mayor 1, Madrid 28001"
"Add a contact to Acme SL: Ana Garcia, CTO, ana@acme.es"
"Log a call with TechStart: discussed Q2 proposal, they're interested in upgrade"
"Add a note to ClientName: prefers invoices in English, payment NET 30"
"Show me all activities for Acme SL"
This MCP is a structured data interface -- you describe what you want in natural language, and the AI creates, queries, or modifies business records in Frihet. All 157 tools are CRUD operations over the REST API.
Works great:
"Create an invoice for TechStart SL, 40h consulting at 75 EUR/h" --> creates the invoice
"Show unpaid invoices over 1,000 EUR" --> queries and filters
"Log a 120 EUR expense for the Madrid train, category: travel" --> records the expense
"Update client Acme's email to billing@acme.es" --> modifies the record
Does not do:
OCR or PDF scanning -- you cannot upload an invoice image and have it read
File upload or attachment handling
Image processing of any kind
If you need to digitize paper invoices or receipts, extract the data first (e.g., Claude Vision API, a dedicated OCR service, or manual entry), then use the MCP to create the record:
1. Scan/photograph the invoice
2. Use Claude Vision: "Read this invoice image and extract the vendor, items, amounts, and dates"
3. Then: "Create an expense in Frihet for [extracted data]"
Close an accounting period (gestor/admin only — TRUST AREA)
period_reopen
Reopen a closed period with a mandatory reason (TRUST AREA)
All 157 tools return structured output via outputSchema -- typed JSON, not raw text. List tools return paginated results ({ data, total, limit, offset }).
graph LR
AI["Your AI assistant"]
MCP["frihet-mcp"]
API["api.frihet.io"]
DB["Frihet ERP"]
AI -- "create_invoice()" --> MCP
MCP -- "POST /v1/invoices" --> API
API --> DB
DB -- "201 + invoice data" --> API
API -- "structured JSON" --> MCP
MCP -- "typed response + suggestions" --> AI
style AI fill:#09090b,stroke:#4ade80,color:#fafafa
style MCP fill:#09090b,stroke:#fafafa,color:#fafafa
style API fill:#09090b,stroke:#3f3f46,color:#a1a1aa
style DB fill:#09090b,stroke:#3f3f46,color:#a1a1aa
The server translates tool calls into REST API requests. It handles authentication, rate limiting (automatic retry with backoff on 429), pagination, and error mapping.
Two transports:
stdio (local) -- npx @frihet/mcp-server with FRIHET_API_KEY
Streamable HTTP (remote) -- https://mcp.frihet.io/mcp with Bearer token or OAuth 2.0+PKCE
Frihet's differentiator is depth — full ES/EU fiscal coverage plus native compliance (VeriFactu, TicketBAI, Facturae/FACe/KSeF), banking, CRM, HR/payroll, stay/PMS and POS. But a flat list of every tool, loaded into an agent's context up front, is the 2026 context-rot problem: it crowds out the task and degrades tool selection before any work begins.
FRIHET_TOOL_MODE lets you choose how that depth is exposed.
Mode
Behavior
full (default)
All tools are exposed with their full descriptions and schemas. Unchanged from previous releases — existing setups are unaffected.
grouped
Progressive disclosure. Each tool's description collapses to a one-line [group] summary — full schema via describe_tool('name'), and three lightweight discovery tools are added. The agent loads depth only for the tools it actually needs.
In grouped mode the tools are unchanged — same names, same input schemas, same behavior. Only the up-front context cost changes. Discovery flows through three meta-tools:
list_tool_groups() — the domain map (invoicing, expenses, fiscal/compliance, banking, CRM, HR/payroll, stay/PMS, POS, intelligence, products, platform) with a one-line blurb and tool count for each.
search_tools(query) — free-text search across tool name, title, summary and group; returns matching tools with their group, summary, read-only flag and input fields. Optional group filter and limit.
describe_tool(name) — the full original description and input fields for one tool, on demand, before you call it.
// claude_desktop_config.json — opt in to grouped mode{"mcpServers":{"frihet":{"command":"npx","args":["@frihet/mcp-server"],"env":{"FRIHET_API_KEY":"fri_...","FRIHET_TOOL_MODE":"grouped"}}}}
This is an opt-in exposure layer only — it never changes a tool's logic, name or behavior, and full mode is byte-identical to before. The same interceptor pattern powers the OpenAI-safe profile (FRIHET_OPENAI_MODE).
Beyond raw MCP tools, this repo includes a Claude Code skill that adds business context: Spanish tax rules, workflow recipes, financial reports, and natural language commands.
