@frihet/mcp Server

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

Works withClaude·ChatGPT·Cursor·Windsurf·Cline·Antigravity·Codex·Copilot·Gemini CLI— and any MCP-compatible client.

Surface truth:the catalogue contains 157 canonical operations. The local full profile serves those plus 5 fiscal alias names (162 names). The hosted grouped profile also adds 3 local discovery names (165 names). Catalogue membership is not a promise that a backing API is enabled for every workspace.

An MCP server that connects your AI assistant toFrihet. 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.

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

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

/plugin marketplace add anthropics/claude-plugins-community /plugin install frihet-erp@claude-community

Skill invocation:/frihet-erp:frihet-mcp. The bundled.mcp.jsonlaunches@frihet/mcp-servervianpx— setFRIHET_API_KEYin your environment (get one atapp.frihet.io→ Settings → API keys).

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

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

{ "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 tohttps://mcp.frihet.io/mcpand authenticate via browser. The server implements the full OAuth 2.1 authorization code flow with PKCE.
- Log intoapp.frihet.io
- Go toSettings > API
- ClickCreate API key
- Copy the key (starts withfri_) -- it's only shown once

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

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

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

"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

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

Impuesto sobre Sociedades — Corporate Tax (2)

All canonical operations (and their aliases) returnstructured outputviaoutputSchema-- typed JSON, not raw text. List response shapes follow their API family; not every list endpoint is paginated.

On the full MCP surfaces, everytools/listentry includes_meta["io.frihet/capability"]:

- registeredmeans the name and handler exist in this server build;
- callabilityisapi_dependent(the handler calls the API; deployment, workspace enablement, and authorization still decide),runtime_checked(the handler explicitly distinguishes an absent backend from empty data),deferred,unavailable, orlocal—never an unconditional “available” claim;
- writesFrihet,externalInteraction, andexternalSideEffectsdistinguish state changes and calls to external entities/providers;
- MCP action annotations remain the standard source for read-only, destructive, idempotent, and open-world hints.

The ChatGPT/OpenAI host is a separately reviewed surface: 53 reviewed business operations plus 3 discovery names, with 0 prompts and 0 resources. It must not be inferred from the full catalogue.

Context the AI can read to make smarter decisions.

The local package serves 11 resources: 7 static references plus 4 API-backed workspace resources. The hosted Worker serves the 7 static resources. The OpenAI-reviewed host serves 0 resources.

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

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.

- stdio(local) --npx @frihet/mcp-serverwithFRIHET_API_KEY
- Streamable HTTP(remote) --https://mcp.frihet.io/mcpwith Bearer token or OAuth 2.0+PKCE

Frihet's differentiator isdepth— full ES/EU fiscal coverage plus native compliance (VeriFactu, TicketBAI, Facturae/FACe; KSeF Poland infra-ready, activation pending), 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_MODElets you choose how that depth is exposed.

Ingroupedmode operation names, input schemas and handlers are unchanged. Descriptors also expose the same conservative capability and action truth as the full profile. 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. Optionalgroupfilter andlimit.
- 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" } } } }

Grouped exposure changes description density, not operation behavior. The frozen OpenAI-reviewed profile is composed separately and remains independently gated.

Rate limiting is handled automatically with exponential backoff.

Beyond raw MCP tools, this repo includes aClaude Code skillthat adds business context: Spanish tax rules, workflow recipes, financial reports, and natural language commands.

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

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

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

FRIHET_API_KEY=fri_xxx node dist/index.js

npx @modelcontextprotocol/inspector node dist/index.js

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

- No OCR or file upload-- the MCP works with structured data, not images or PDFs.
- Single company-- one API key maps to one Frihet workspace.
- Frihet account required-- you need an active account atapp.frihet.ioand an API key (starts withfri_).

- 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
- Security policy-- Private vulnerability reporting guidance

Paid remote MCP for agentic workflow budget quotes, policy checks, spend approvals, usage receipts, and cost evidence exports.