frihet-mcp

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="./assets/banner.svg"> <source media="(prefers-color-scheme: light)" srcset="./assets/banner-light.svg"> <img alt="frihet-mcp" src="./assets/banner.svg" width="100%"/> </picture> </p> <p align="center"> <strong>AI-native MCP server for business management.</strong><br/> <em>Servidor MCP nativo con IA para gestión empresarial.</em> </p> <p align="center"> _{Works with <strong>Claude</strong> · <strong>ChatGPT</strong> · <strong>Cursor</strong> · <strong>Windsurf</strong> · <strong>Cline</strong> · <strong>Antigravity</strong> · <strong>Codex</strong> · <strong>Copilot</strong> · <strong>Gemini CLI</strong> — and any MCP-compatible client.} </p> <p align="center"> <a href="https://www.npmjs.com/package/@frihet/mcp-server"><img src="https://img.shields.io/npm/v/@frihet/mcp-server?style=flat&color=18181b&labelColor=09090b" alt="npm version"></a> <a href="https://www.npmjs.com/package/@frihet/mcp-server"><img src="https://img.shields.io/npm/dm/@frihet/mcp-server?style=flat&color=18181b&labelColor=09090b&label=downloads" alt="npm downloads"></a> <a href="https://smithery.ai/servers/frihet/frihet-mcp"><img src="https://smithery.ai/badge/frihet/frihet-mcp" alt="Smithery installs"></a> <a href="https://registry.modelcontextprotocol.io/?q=io.frihet"><img src="https://img.shields.io/badge/MCP_Registry-io.frihet%2Ferp-4A90D9?style=flat&logo=anthropic&logoColor=white" alt="MCP Registry"></a> <a href="https://github.com/mcp/io.frihet/erp"><img src="https://img.shields.io/badge/GitHub_MCP_Registry-Listed-18181b?style=flat&labelColor=09090b&logo=github" alt="Listed in GitHub MCP Registry"></a> <a href="https://github.com/Frihet-io/frihet-mcp/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-18181b?style=flat&labelColor=09090b" alt="license"></a> <img src="https://img.shields.io/badge/catalogue-158_operations-18181b?style=flat&labelColor=09090b" alt="158 canonical catalogue operations"> <img src="https://img.shields.io/badge/node-%3E%3D20-18181b?style=flat&labelColor=09090b" alt="node >=20"> <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-18181b?style=flat&labelColor=09090b" alt="TypeScript"></a> </p> <p align="center"> <img src="https://raw.githubusercontent.com/Frihet-io/frihet-mcp/main/assets/demo-tour.gif" alt="Frihet MCP — talk to your ERP in natural language" width="82%"> </p>

---

Distribution

| Channel | Status | Install | |---------|--------|---------| | npm | Live | npx @frihet/mcp-server | | Remote endpoint | Live | https://mcp.frihet.io/mcp (zero install, OAuth or API key) | | Smithery | Live | smithery.ai/servers/frihet/frihet-mcp | | MCP Registry | Live | registry.modelcontextprotocol.io | | GitHub MCP Registry | Live | github.com/mcp/io.frihet/erp | | Glama | Live | glama.ai/mcp/servers/Frihet-io/frihet-mcp | | mcp.so | Auto-index (unverified) | mcp.so — indexes from npm + GitHub | | PulseMCP | Auto-index (unverified) | pulsemcp.com — indexes from npm + GitHub | | Cursor Marketplace | Coming soon | cursor.com/marketplace | | ChatGPT Apps | Coming soon | chatgpt.com | | Anthropic Claude Directory | Coming soon | claude.ai/settings/connectors |

Surface truth: the catalogue contains 158 canonical operations. The local full profile serves 163 tool names, 11 resources, and 10 prompts (158 canonical operations plus 5 fiscal aliases). The hosted grouped profile serves 166 tool names, 7 resources, and 10 prompts (the same names plus 3 discovery tools, with API-backed resources kept local-only). The separately reviewed OpenAI profile serves 33 tool names, 0 resources, and 0 prompts. Catalogue membership is not a promise that a backing API is enabled for every workspace.

---

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.

158 canonical operations. Five fiscal aliases. Ten prompts. The local package serves 11 resources; the hosted Worker deliberately serves the 7 static resources, while API-backed workspace resources remain local-profile only.

<!-- v1.12.0-beta.1 — D4-B megasprint: HR (9), payroll (2), onboarding (2), permissions (2), period close (3), webhook test (1) = +19 = 158 tools total -->

---

Try it instantly (no signup)

Kick the tires with zero setup — no account, no API key:

FRIHET_DEMO=1 npx -y @frihet/mcp-server

In demo mode the server answers from realistic example fixtures (Spanish invoices with IVA/IGIC, expenses, clients, products, a bank account, and more) — every record uses demo_-prefixed IDs and the server prints a DEMO MODE banner on startup. Nothing is persisted and no network call is ever made. Writes are simulated and fiscal actions (e-invoice, VeriFactu, TicketBAI, FACe, payroll) return a clearly-labeled simulation — never a real submission to any tax authority.

When you're ready for your real data, drop the flag and add your key (app.frihet.io → Settings → API keys). See Install below.

---

For AI agents

If you are an agent reading this repository rather than a person reading a page, everything you need is machine-readable and generated from the running server — you do not have to parse this README.

| What | Where | |------|-------| | Onboarding contract: quickstart per client, auth, safe workflow, human-authority tool lists, error recovery | docs/agent-onboarding.json — also shipped inside the npm package | | Per-tool capability truth: callability, writesFrihet, externalInteraction, externalSideEffects | _meta["io.frihet/capability"] on every entry of tools/list | | How to behave once connected | the instructions string returned by initialize — your client hands it to you automatically |

Three rules the contract encodes, in short:

1. Orient before acting. get_business_context and the frihet://tax/rates resource decide the correct fiscal treatment. Do not recall a Spanish tax rate from memory.
2. Draft, show, stop. create_invoice, create_quote and create_credit_note all default to status=draft — no fiscal number, no hash, nothing sent to a tax authority. Present the draft and hand back.
3. Human authority is not yours to assume. Any tool with a non-empty externalSideEffects reaches a client's inbox, a webhook, money, or AEAT / VeriFactu / TicketBAI / FACe. Several also take confirm=true; that flag records a human decision — never set it to satisfy your own plan.

docs/agent-onboarding.json is regenerated from the live surface by npm run generate:agent-onboarding and gated in CI by npm run gate:agent-onboarding, so its tool lists and counts cannot drift from the server.

---

Install

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

npx skills add Frihet-io/frihet-mcp

Claude Code plugin (skill + MCP server in one install)

This repository is also a Claude Code plugin (frihet-erp): installing it wires up both the business-management skill and the MCP server.

# Try it locally
claude --plugin-dir /path/to/frihet-mcp

Marketplace availability is pending. Use the local plugin command above or the Claude Code MCP command below to connect today.

Skill invocation: /frihet-erp:frihet-mcp. The bundled .mcp.json launches @frihet/mcp-server via npx — set FRIHET_API_KEY in your environment (get one at app.frihet.io → Settings → API keys).

Claude Code — one command

claude mcp add frihet -s user -e FRIHET_API_KEY=fri_…[redacted] -- npx -y @frihet/mcp-server
claude mcp list          # verify: frihet ✓ Connected

The CLI owns the config file, so there is nothing to hand-edit and no path to get wrong. (User scope writes ~/.claude.json, not ~/.claude/mcp.json.)

Codex CLI — one command

codex mcp add frihet --env FRIHET_API_KEY=fri_…[redacted] -- npx -y @frihet/mcp-server
codex mcp list           # verify

Codex config is TOML, not JSON. codex mcp add writes:

[mcp_servers.frihet]
command = "npx"
args = ["-y", "@frihet/mcp-server"]

[mcp_servers.frihet.env]
FRIHET_API_KEY = "fri_…[redacted]"

Pasting a JSON mcpServers block into ~/.codex/config.toml is a TOML parse error that takes down your whole Codex config, not just this server. Use the command above.

Claude Desktop, Cursor, Windsurf, Cline — JSON config

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

| Tool | Config file | |------|------------| | Claude Desktop | ~/Library/Application Support/Claude/claude_desktop_config.json | | Cursor | .cursor/mcp.json or ~/.cursor/mcp.json | | Windsurf | ~/.windsurf/mcp.json | | Cline | VS Code settings or .cline/mcp.json |

The JSON above is identical for these four clients; only the file path changes. Claude Code and Codex are not in this table — they manage their own config through the CLI commands shown above.

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