Frihet MCP

Frihet MCP Skill

Business assistant inside Claude Code. Manage invoices, expenses, clients, products, and quotes in plain language — with built-in Spanish tax intelligence.

Requires: Frihet account with API access + @frihet/mcp-server configured as MCP server.

Setup

1. Configure the MCP server

Add to your Claude Code MCP config (~/.claude/mcp.json or project .mcp.json):

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

Get your API key at app.frihet.io > Settings > API.

2. Verify

Run /frihet status — if you see your account info, you're ready.

Commands

MCP catalogue (158 canonical operations)

The table below lists the core resource groups. The catalogue contains 158 canonical operations across 20+ domains; alias and discovery names are profile-specific. See the README catalogue for the full list and capability semantics.

Core Decision Logic

Tax Rate Selection

Determine the correct tax based on the client's fiscal zone:

Decision flow for invoices:

1. Check the client's address/fiscal zone
2. If peninsula → apply IVA at the rate matching the product/service type
3. If canarias → apply IGIC instead of IVA
4. If eu → 0% with "Inversión del sujeto pasivo" / "Reverse charge" note
5. If world → 0% exempt, no tax line

IRPF retention (professional services only):

• Standard: 15%
• New autónomo (first 3 years): 7%
• Only applies when invoicing as a professional to a business (B2B peninsula)

For full tax details including quarterly models, deadlines, and expense deductibility rules, see references/tax-guide.md.

Expense Categorization

Auto-categorize expenses by matching keywords in the description:

Invoice Status Flow

draft → sent → paid
              → overdue → paid
                        → cancelled

Rectificativa (credit note) types, per the LIVA article each one keys on: R1 (art. 80.1-2 / 80.6 — error in law, returns, retroactive discounts), R2 (art. 80.3 — concurso de acreedores, i.e. a court has declared the customer insolvent), R3 (art. 80.4 — wholly or partly uncollectible debt), R4 (anything else), R5 (rectifying a simplified invoice).

create_credit_note only reaches R1 and R4: the type is derived server-side from reason (error -> R1, everything else -> R4). R2, R3 and R5 exist in the regulation but cannot be selected through the API — use the app. The tool creates a DRAFT (no fiscal number, no hash, not submitted to VeriFactu), always rectifies by differences (TipoRectificativa = I), and only does full credits — fullCredit: false returns 400 PARTIAL_CREDIT_NOT_IMPLEMENTED.

Quote Status Flow

draft → sent → accepted → (convert to invoice)
             → rejected
             → expired

Key Workflows

Brief workflow outlines — for detailed step-by-step recipes, see references/workflows.md.

Monthly close ("cierre mensual"): List month's invoices + expenses → calculate income, expenses, IVA collected vs paid, net result → flag unpaid invoices.

Tax prep 303 ("IVA trimestral", "303"): Sum quarter's IVA repercutido (invoices) - IVA soportado (deductible expenses) → present pre-filled 303 data.

Client onboarding: Create client → optionally create product → create invoice → confirm.

Expense batch ("gastos del mes"): Parse multiple expenses → create each with auto-categorized category → summary table with deductible split.

Overdue follow-up ("morosos"): List overdue invoices → sort by amount → suggest follow-up actions.

Quote to invoice: Get accepted quote → create invoice copying client/items/notes → mark quote as accepted.

Error Handling

For full error code reference and pagination patterns, see references/api-patterns.md.

Language Rules

• Respond in the same language the user writes in
• Default to Spanish (ES) for financial terms and tax references
• Keep Spanish terms for tax models (Modelo 303, IRPF, IVA) even in English — they have no direct translation
• Currency is always EUR. Format: 1,234.56 EUR (dot for decimals, comma for thousands)

Security

• Never log, display, or store the API key in conversation output
• Never include the API key in code snippets shown to the user
• API key is managed exclusively via environment variables in MCP config
• All data stays between Claude Code, the MCP server, and Frihet's API
• The MCP server is stateless — stores nothing
• If a user asks to see their API key, direct them to app.frihet.io

References

• references/tax-guide.md — Full Spanish tax knowledge: IVA/IGIC/IRPF rates, fiscal zones, quarterly calendar, expense deductibility, VeriFactu, Crea y Crece
• references/workflows.md — Detailed workflow recipes with step-by-step MCP tool calls and response formatting templates
• references/api-patterns.md — API rate limits, pagination, error codes, response formatting conventions

Links

• App: https://app.frihet.io
• Docs: https://docs.frihet.io/desarrolladores
• API Reference: https://docs.frihet.io/desarrolladores/api-rest
• MCP Server (npm): https://www.npmjs.com/package/@frihet/mcp-server
• Source Code: https://github.com/Frihet-io/frihet-mcp
• Remote MCP: https://mcp.frihet.io
• Support: soporte@frihet.io