Frihet MCP Server
About
The first AI-native MCP server for a Spanish ERP. Create invoices, manage expenses, track clients, handle products, quotes and webhooks — all through natural language with any AI assistant. 31 tools, bilingual ES/EN.
Details
- Author
- berthelius
- Categories
- Other, Developer Tools
Jump to
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
Once available in the community marketplace:
/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 at](#install)app.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
Talk to your ERP. These are real prompts, not marketing copy.
"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"
This MCP is astructured data interface-- you describe what you want in natural language, and the AI creates, queries, or modifies business records in Frihet. Most of the 157 canonical operations are CRUD operations over the REST API; the rest are read-only summaries and fiscal/e-invoice actions. Alias and discovery names are counted separately.
"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
- 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]"
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.
157 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.
Kick the tires with zero setup — no account, no API key:
In demo mode the server answers from realisticexample fixtures(Spanish invoices with IVA/IGIC, expenses, clients, products, a bank account, and more) — every record usesdemo_-prefixed IDs and the server prints aDEMO MODEbanner on startup.Nothing is persistedand 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). SeeInstallbelow.
One-line (Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI, and more)
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
Once available in the community marketplace:
/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
Talk to your ERP. These are real prompts, not marketing copy.
"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"
This MCP is astructured data interface-- you describe what you want in natural language, and the AI creates, queries, or modifies business records in Frihet. Most of the 157 canonical operations are CRUD operations over the REST API; the rest are read-only summaries and fiscal/e-invoice actions. Alias and discovery names are counted separately.
"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
- 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]"
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
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
- 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
Chia Health MCP Server — Patient workflow integration for a licensed US telehealth platform. Browse GLP-1 medications (semaglutide, tirzepatide), peptide therapies (sermorelin, NAD+, glutathione), and longevity treatments. Check eligibility, complete intake, sign consents, and manage treatment plans. 30 tools, HIPAA-compliant. All prescriptions evaluated by licensed US healthcare providers and delivered from FDA-regulated pharmacies across 50 states + DC.
Broker + MCP server for last-bidder-wins games on Solana — agents register, auto-fund a Privy wallet, and bid via streamable HTTP
AI-powered no-code app builder with 17 MCP tools — create projects, generate pages from natural language, AI text/image generation (GPT, Claude, Gemini, 14+ models), page CRUD, workflow execution, publish & version control. SSE transport, API key auth.
An mcp server for your food ordering needs.
Agent-to-Agent handoff certification for multi-agent systems — validates context preservation, verifies agent capabilities before handoff, logs transfer chains, and ensures no data loss in agent orchestration.
Unified MCP & skill management gateway with progressive disclosure. Manages multiple MCP servers as Agent Apps, loading tool schemas on demand for 99% context token savings. Shared across Claude Code, Codex, OpenCode and more.
A collection of Model Context Protocol (MCP) servers for various tasks and integrations, supporting both Python and Node.js environments.
Open-souSecurely feeds real security refreshed rules into Cursor, Claude Code, and Windsurf — zero config, no API key.
Health intelligence MCP — access biomarkers, biological age, and personalized longevity action plans from your Aniva profile.
Real-time stock heatmaps and investment tools delivered as interactive React components.
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
