Frihet ERP

AI-native MCP server for business management.
Servidor MCP nativo con IA para gestión empresarial.

---

Distribution

Tool count: npm latest (1.14.0) ships all 157 tools, same as the remote endpoint (mcp.frihet.io).

---

What is this

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.

---

Install

One-line (Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI, and more)

npx skills add Frihet-io/frihet-mcp

Claude Code / Claude Desktop

{
  "mcpServers": {
    "frihet": {
      "command": "npx",
      "args": ["-y", "@frihet/mcp-server"],
      "env": {
        "FRIHET_API_KEY": "fri_your_key_here"
      }
    }
  }
}

The JSON config is identical for all tools. Only the file path changes.

Remote (no install)

Use the hosted endpoint at mcp.frihet.io -- zero local dependencies, runs on Cloudflare Workers.

With API key:

{
  "mcpServers": {
    "frihet": {
      "type": "streamable-http",
      "url": "https://mcp.frihet.io/mcp",
      "headers": {
        "Authorization": "Bearer fri_your_key_here"
      }
    }
  }
}

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.

Get your API key

1. Log into app.frihet.io
2. Go to Settings > API
3. Click Create API key
4. Copy the key (starts with fri_) -- it's only shown once

---

What you can do

Talk to your ERP. These are real prompts, not marketing copy.

Invoicing

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

Expenses

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

Clients

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

CRM

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

Quotes

"Create a quote for Design Studio: logo design (2000 EUR) + brand guidelines (3500 EUR)"
"Show me all pending quotes"

Webhooks

"Set up a webhook to notify https://my-app.com/hook when invoices are paid"
"List all my active webhooks"

---

What to expect

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

---

Tools (157)

Invoices (12)

Expenses (5)

Clients (5)

CRM: Contacts (3)

CRM: Activities (2)

CRM: Notes (3)

Products (5)

Quotes (6)

Webhooks (6)

Intelligence (4)

E-Invoicing (10)

Status: beta. Tools call api.frihet.io/v1/einvoice/* directly. If an endpoint is not yet deployed (404), the tool falls back to { _stub: true, _note: "CF endpoint pending deploy", _plannedEndpoint: "..." } so the server remains usable while transport ships.

Time Tracking (6)

Status: stub — /v1/time/* endpoints planned. Tools surface 404 until backend ships.

Recurring Invoices (8)

Status: stub — /v1/recurring/* endpoints planned. Tools surface 404 until backend ships.

Team Management (4)

Status: stub — /v1/team/* endpoints planned. Tools surface 404 until backend ships.

Gestoria — Accountants (5)

Status: stub — /v1/gestoria/* REST surface lands with Wave Fase 1 closure (PRs #383 bulk send, #384 aging, #385 messaging). Tools surface 404 until the backend ships.

Audit GL (3)

Status: stub — /v1/gl/* proxies callables approveGLEntry, rejectGLEntry, getGLEntryAuditLog (PR #395). Tools surface 404 until backend ships.

White-label Portal Domain (3)

Status: stub — /v1/portal/domain/* proxies callables addCustomPortalDomain, verifyCustomPortalDomain, removeCustomPortalDomain (PR #397).

Self-onboard & VIES (2)

Status: stub — /v1/portal/onboard/* proxies callables generatePortalOnboardLink, lookupTaxIdViaVIES (PR #398). Public portal flows excluded from MCP.

IGIC — Canary Islands Indirect Tax (4)

Status: stub — /v1/igic/* service-layer reads (PR #390). ATC SOAP excluded (internal infra).

Impuesto sobre Sociedades — Corporate Tax (2)

Status: stub — /v1/is/* service-layer reads for Spanish SLs/SAs (PR #392).

Bank Categorization Rules (2)

Status: stub — /v1/banking/rules Q3-flagged (PR #394). Webhook handlers excluded.

Deposits (7)

Vendors (5)

Banking (5)

Fiscal — Spanish Tax Models (8)

Vacation Rentals / Stay (5)

POS — Point of Sale (4)

HR — Human Resources (9)

Payroll (2)

Onboarding (2)

Permissions (2)

Period Close (3)

All 157 tools return structured output via outputSchema -- typed JSON, not raw text. List tools return paginated results ({ data, total, limit, offset }).

---

Resources (11)

Context the AI can read to make smarter decisions.

Static (reference data, no API calls):

Dynamic (live data from your account):

---

Prompts (10)

Pre-built workflows the AI can execute as guided multi-step operations.

---

How it works

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

Environment variables

---

Tool exposure: depth served on demand

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.

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).

---

API limits

Rate limiting is handled automatically with exponential backoff.

---

Claude Code Skill

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.

Install the skill

git clone https://github.com/Frihet-io/frihet-mcp.git
ln -s "$(pwd)/frihet-mcp/skill" ~/.claude/skills/frihet

Or with the universal installer:

npx skills add Frihet-io/frihet-mcp

Commands

The skill knows about IVA rates, IRPF retention, Modelo 303 prep, expense deductibility rules, and VeriFactu compliance.

Full documentation: docs.frihet.io/desarrolladores/skill-claude-code

---

Development

git clone https://github.com/Frihet-io/frihet-mcp.git
cd frihet-mcp
npm install
npm run build

Run locally:

FRIHET_API_KEY=fri_xxx node dist/index.js

Test with the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

---

Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

git clone https://github.com/Frihet-io/frihet-mcp.git
cd frihet-mcp
npm install
npm run build   # must pass before submitting

---

Current limitations

• No OCR or file upload -- the MCP works with structured data, not images or PDFs. Planned for a future release.
• Single company -- one API key maps to one Frihet workspace. Multi-company support is not yet available.
• Frihet account required -- you need an active account at app.frihet.io and an API key (starts with fri_).

---

Ecosystem

Links

• Frihet -- The product
• Documentation -- Full docs
• API reference -- REST API
• MCP server docs -- Setup guides, troubleshooting
• npm -- Package registry
• Smithery -- Smithery marketplace
• MCP Registry -- Anthropic official registry
• Remote endpoint -- Hosted MCP server (Cloudflare Workers)
• OpenAPI spec -- Machine-readable API definition

---

License

MIT. See LICENSE.

Built by Frihet.