MCP-server

Frihets MCP-server implementerar Model Context Protocol så att AI-assistenter kan interagera direkt med ditt ERP. Skapa fakturor, registrera utgifter, konsultera kunder eller hantera offerter – allt från din IDE eller terminal, på naturligt språk.

Du:      "Skapa en faktura för TechStart SL, 40 timmars konsultation till 75 EUR/timme, förfallodatum 1 mars"
Claude:  Klart. Faktura INV-2026-089 skapad. Totalt: 3 000,00 EUR + 21 % moms = 3 630,00 EUR.

Vad du kan förvänta dig (och inte)

MCP-servern är en tillståndslös brygga mellan din AI-assistent och Frihets REST API. Varje verktygsanrop översätts till en HTTP-förfrågan till API:et.

Vad den GÖR:

Komplett CRUD på fakturor, utgifter, kunder, produkter, offerter och webhooks
Sökning av fakturor efter kundnamn
Åtkomst till referensdata (skattesatser, skattekalender, kategorier)
Guidade arbetsflöden (månadsavslut, skatteförberedelse, uppföljning av förfallna fordringar)

Vad den INTE gör:

OCR av dokument (detta gör AI-assistenten inom appen)
PDF-generering (använd REST API direkt: GET /v1/invoices/:id/pdf)
Betalningshantering (betalningar hanteras via Stripe Connect i appen)

Krav

Frihet-konto med API-åtkomst (betalda planer)
API-nyckel genererad från panelen

Hämta API-nyckeln

Logga in på app.frihet.io
Gå till Inställningar > Utvecklare > API-nycklar
Klicka på Skapa API-nyckel
Kopiera nyckeln (börjar med fri_) — den visas bara en gång

Installation

Universal (30+ agenter)

Det snabbaste sättet att installera MCP-servern och företagskompetensen:

npx skills add Frihet-io/frihet-mcp

Fungerar med Claude Code, Cursor, Copilot, Codex, Windsurf, Gemini CLI, Goose, Roo Code, och 30+ fler agenter.

MCP Registry

Servern är registrerad som io.frihet/erp i det officiella MCP Registry. MCP-klienter som stöder registret kan automatiskt upptäcka och installera det via dess kanoniska namn.

Direkt npx

npx -y @frihet/mcp-server@latest

Du behöver inte installera något globalt. npx laddar ner och kör den senaste versionen automatiskt.

Manuell konfiguration

Det finns två anslutningslägen: lokal (servern körs på din maskin via npx) och fjärr (direkt anslutning till mcp.frihet.io, utan att installera något).

Lokal (stdio)

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

Fjärr (streamable-http)

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

Konfiguration per klient

JSON-strukturen är identisk i alla klienter. Endast konfigurationsfilens plats ändras.

Klient	Konfigurationsfil
Claude Code	`~/.claude/mcp.json`
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
Cursor	`.cursor/mcp.json` eller `~/.cursor/mcp.json`
Windsurf	`~/.windsurf/mcp.json`
Cline	VS Code-konfiguration eller `.cline/mcp.json`
Codex CLI	`~/.codex/config.toml` (MCP-sektion)

tips

Om du använder Claude Code, kan du lägga till servern med ett enda kommando:

claude mcp add frihet -- npx -y @frihet/mcp-server@latest

Konfigurera sedan variabeln FRIHET_API_KEY i filen ~/.claude/mcp.json som resulterar.

Miljövariabler

Variabel	Obligatorisk	Standardvärde
`FRIHET_API_KEY`	Ja	--
`FRIHET_API_URL`	Nej	`https://api.frihet.io/v1`
`FRIHET_MCP_DEBUG`	Nej	`0`

FRIHET_API_URL är användbar om du pekar mot en staging-miljö eller en anpassad instans. Det måste vara https:// med ett värdnamn under frihet.io.
FRIHET_MCP_DEBUG=1 aktiverar debug-loggar (användbart för att diagnostisera problem).

OAuth-flöde

MCP-servern stöder OAuth-autentisering utöver manuell API-nyckel. När en MCP-klient initierar OAuth-flödet:

Användaren autentiserar sig via Firebase Auth (e-post, Google, GitHub eller Microsoft)
Klienten skickar sessions-token till POST /api/oauth/api-key
Servern tillhandahåller en ny nyckel fri_xxx... märkt "MCP OAuth" med utgångsdatum 365 dagar
Nyckeln används automatiskt för efterföljande anrop

Detta tillåter användare att ansluta MCP-servern utan att kopiera nycklar manuellt.

Tillgängliga verktyg (44)

Servern exponerar 52 verktyg organiserade i 7 kategorier. Varje verktyg inkluderar strukturerad utdata (outputSchema + structuredContent) så att assistenter kan tolka svar på ett tillförlitligt sätt, samt säkerhets- och innehållsannoteringar. Tvåspråkig (EN/ES).

Fakturor (6 verktyg)

Verktyg	Beskrivning	Nyckelparametrar
`list_invoices`	Listar fakturor med paginering	`limit`, `offset`
`get_invoice`	Hämta en faktura med ID	`id`
`create_invoice`	Skapa en faktura med detaljerade rader	`clientName`, `items[]` (description, quantity, unitPrice), `status`, `dueDate`, `notes`, `taxRate`
`update_invoice`	Uppdatera fält för en faktura (partiellt)	`id`, och eventuella fält att modifiera
`delete_invoice`	Ta bort en faktura permanent	`id`
`search_invoices`	Sök fakturor efter kundnamn	`clientName`, `limit`, `offset`

Möjliga fakturastatusar: draft (utkast), sent (skickad), paid (betald), overdue (förfallen), cancelled (annullerad)

Utgifter (5 verktyg)

Verktyg	Beskrivning	Nyckelparametrar
`list_expenses`	Listar utgifter med paginering	`limit`, `offset`
`get_expense`	Hämta en utgift med ID	`id`
`create_expense`	Registrera en ny utgift	`description`, `amount`, `category`, `date`, `vendor`, `taxDeductible`
`update_expense`	Modifiera en befintlig utgift (partiellt)	`id`, och eventuella fält att modifiera
`delete_expense`	Ta bort en utgift permanent	`id`

Kunder (5 verktyg)

Verktyg	Beskrivning	Nyckelparametrar
`list_clients`	Listar alla kunder	`limit`, `offset`
`get_client`	Hämta en kund med ID	`id`
`create_client`	Registrera en ny kund	`name`, `email`, `phone`, `taxId`, `address` (street, city, state, postalCode, country)
`update_client`	Uppdatera kunddata (partiellt)	`id`, och eventuella fält att modifiera
`delete_client`	Ta bort en kund permanent	`id`

Produkter (5 verktyg)

Verktyg	Beskrivning	Nyckelparametrar
`list_products`	Listar produkter och tjänster	`limit`, `offset`
`get_product`	Hämta en produkt med ID	`id`
`create_product`	Skapa en produkt eller tjänst	`name`, `unitPrice`, `description`, `taxRate`
`update_product`	Modifiera en befintlig produkt (partiellt)	`id`, och eventuella fält att modifiera
`delete_product`	Ta bort en produkt permanent	`id`

Offerter (5 verktyg)

Verktyg	Beskrivning	Nyckelparametrar
`list_quotes`	Listar offerter	`limit`, `offset`
`get_quote`	Hämta en offert med ID	`id`
`create_quote`	Skapa en offert för en kund	`clientName`, `items[]` (description, quantity, unitPrice), `validUntil`, `notes`, `status`
`update_quote`	Modifiera en offert (partiellt)	`id`, och eventuella fält att modifiera
`delete_quote`	Ta bort en offert permanent	`id`

Möjliga offertstatusar: draft (utkast), sent (skickad), accepted (accepterad), rejected (avvisad), expired (förfallen)

Webhooks (5 verktyg)

Verktyg	Beskrivning	Nyckelparametrar
`list_webhooks`	Listar konfigurerade webhooks	`limit`, `offset`
`get_webhook`	Hämta webhook-konfiguration	`id`
`create_webhook`	Registrera en webhook-slutpunkt	`url`, `events[]`, `active`, `secret`
`update_webhook`	Modifiera en befintlig webhook	`id`, och eventuella fält att modifiera
`delete_webhook`	Ta bort en webhook permanent	`id`

Tillgängliga webhook-händelser: invoice.created, invoice.updated, invoice.deleted, invoice.paid, expense.created, expense.updated, expense.deleted, client.created, client.updated, client.deleted, product.created, product.updated, product.deleted, quote.accepted. Se Webhooks för payload-format och HMAC-verifiering.

Tillgängliga resurser (8)

MCP-resurser är referensdata som assistenten kan konsultera utan att göra API-anrop. De är statiska och alltid tillgängliga.

Resurs	URI	Beskrivning
API-schema	`frihet://api/schema`	Sammanfattning av slutpunkter, autentisering, hastighetsbegränsningar och felkoder
Skattesatser	`frihet://tax/rates`	Moms (21/10/4%), IGIC (7/3/0%), IPSI, intrakommunitär, IRPF (15%/7%)
Skattekalender	`frihet://tax/calendar`	Datum för kvartalsvis inlämning (Formulär 303, 130, 420, 390)
Utgiftskategorier	`frihet://config/expense-categories`	8 kategorier med regler för avdragsrätt och skattebehandling
Fakturastatusar	`frihet://config/invoice-statuses`	Statusflöde (utkast, skickad, betald, förfallen, annullerad) med triggers
Leverantörer	`frihet://config/vendors`	Lista över registrerade leverantörer med skatte- och kontaktuppgifter
Aktiva integrationer	`frihet://config/integrations`	Status för anslutna integrationer (Stripe, Shopify, etc.)
Företagsinställningar	`frihet://config/business`	Företagets skatteuppgifter, skattezon, valuta och preferenser

Tillgängliga prompts (7)

Prompts är guidade arbetsflöden som assistenten exekverar steg för steg. De anropas med namn.

Prompt	Beskrivning	Parametrar
`monthly-close`	Månadsavslut: granska obetalda fakturor, kategorisera utgifter, verifiera skatteåtaganden, generera sammanfattning	`month` (valfritt)
`onboard-client`	Kundregistrering: bestämmer skattesats baserat på plats, skapar post, genererar välkomstoffert	`clientName`, `country`, `region`
`quarterly-tax-prep`	Kvartalsvis skatteförberedelse: samla fakturor, beräkna moms/IGIC, generera förhandsgranskning av Formulär 303/130	`quarter`, `fiscalZone`
`overdue-followup`	Uppföljning av förfallna fordringar: identifiera förfallna fakturor, gruppera per kund, skapa inkassomeddelanden	—
`expense-batch`	Batchhantering av utgifter: kategorisera, tillämpa skatter, verifiera avdragsrätt, skapa med bekräftelse	`fiscalZone`
`vendor-analysis`	Leverantörsanalys: gruppera utgifter per leverantör, beräkna totaler, identifiera trender och besparingsmöjligheter	`period` (valfritt)
`business-health`	Affärshälsoanalys: nyckel-KPI:er, jämförelse med föregående månad, varningar och åtgärdbara rekommendationer	`month` (valfritt)

tips

Du kan anropa en prompt direkt: "Kör månadsavslut för februari" eller "Förbered skatterna för Q1".

Användningsexempel

Dessa är verkliga förfrågningar i naturligt språk som assistenten översätter till MCP-verktygsanrop.

Skapa en faktura

"Crea una factura para Acme SL con 10 horas de consultoria a 95 EUR/hora, vencimiento 15 de marzo"

Assistenten anropar create_invoice med clientName: "Acme SL", en detaljrad (10 x 95) och dueDate: "2026-03-15". Beräknar totalsumman automatiskt.

Registrera en utgift

"Registra un gasto de 59.99 EUR en Adobe Creative Cloud, categoria software, deducible"

Anropar create_expense med description, amount: 59.99, category: "software" och taxDeductible: true.

Sök fakturor för en kund

"Busca todas las facturas de TechStart SL"

Anropar search_invoices med clientName: "TechStart SL" och returnerar träffarna med deras totaler och statusar.

Konsultera förfallna fordringar

"Muestrame todas las facturas sin pagar"

Anropar list_invoices och filtrerar efter status: "sent" eller "overdue", visar de förfallna ordnade efter belopp.

Registrera en ny kund

"Nuevo cliente: Design Studio SL, NIF B87654321, email hola@designstudio.es, Madrid 28001"

Anropar create_client med namn, NIF, e-post och adress.

Konfigurera automatisering

"Crea un webhook para notificar a https://mi-app.com/hook cuando se pague una factura"

Anropar create_webhook med url och events: ["invoice.paid"].

Uppdatera en produkt

"Sube el precio de la hora de consultoria a 85 EUR"

Anropar update_product med produktens id och unitPrice: 85. Endast det angivna fältet modifieras.

Observerbarhet

MCP-servern v1.5.1 inkluderar strukturerad loggning och verktygsmått.

Strukturerad loggning

Alla loggar skickas som JSON till stderr (MCP använder stdout för protokollmeddelanden). Varje post inkluderar:

level: debug, info, warn, error
service: alltid frihet-mcp
timestamp: ISO 8601
tool: verktygsnamn (när tillämpligt)
operation: typ av operation (tool_call, api_call, api_retry, startup, shutdown_metrics)
durationMs: exekveringstid i millisekunder
error: feldetaljer (message, code, statusCode)

Aktivera debug-loggar med FRIHET_MCP_DEBUG=1.

Verktygsmått

Servern registrerar anrop till varje verktyg i minnet: antal anrop, fel och genomsnittlig varaktighet. När servern stängs av (SIGINT/SIGTERM) utfärdas en sammanfattning:

{
  "level": "info",
  "message": "Avstängning efter 3600s — 42 anrop, 1 fel",
  "operation": "shutdown_metrics",
  "metadata": {
    "tools": {
      "list_invoices": { "calls": 15, "errors": 0, "avgMs": 230 },
      "create_invoice": { "calls": 8, "errors": 1, "avgMs": 450 }
    },
    "uptime": 3600
  }
}

Automatisk återförsök vid hastighetsbegränsning

När API:et svarar med 429, försöker servern automatiskt igen med exponentiell backoff (upp till 3 återförsök). Återförsöken loggas:

{
  "level": "warn",
  "message": "Hastighetsbegränsad, försöker igen GET /invoices (försök 2, fördröjning 2000ms)",
  "operation": "api_retry"
}

Du behöver inte hantera hastighetsbegränsningen manuellt — servern gör det åt dig.

Transport

Frihets MCP-server stöder två transportlägen. Båda exponerar samma 52 verktyg, 11 resurser och 10 prompts.

Lokal (stdio)

Servern körs som en lokal process på din maskin. Kommunikationen mellan MCP-klienten och servern använder standardinmatning/utmatning (stdin/stdout).

Kräver: Node.js installerat (laddas ner automatiskt via npx)
Fördel: Lägre latens, fungerar utan internetuppkoppling (förutom för API-anropen)
Användningsfall: Daglig utveckling, intensiv användning, företagsmiljöer med nätverksrestriktioner

Fjärr (streamable-http)

Servern körs på Cloudflare Workers. Din MCP-klient ansluter direkt till https://mcp.frihet.io/mcp via HTTP.

Kräver: Endast internetuppkoppling
Fördel: Ingen lokal installation, inga beroenden, fungerar på vilken enhet som helst
Användningsfall: Snabb konfiguration, team som föredrar att inte installera paket, klienter som endast stöder HTTP-transport

info

Om din MCP-klient inte stöder streamable-http (vissa äldre klienter stöder endast stdio), använd det lokala läget.

Felhantering

Hastighetsbegränsning

API:et tillåter 100 förfrågningar per minut per nyckel. Om gränsen överskrids, returnerar servern ett 429-fel med väntetiden i retryAfter.

MCP-servern hanterar automatiskt hastighetsbegränsningen med exponentiell backoff: den försöker igen efter att ha väntat den angivna tiden, utan användarens ingripande. Maximalt 3 återförsök.

Autentiseringsfel

Kod	Orsak	Lösning
`401`	Ogiltig, utgången eller ej angiven API-nyckel	Kontrollera att nyckeln i din konfiguration börjar med `fri_` och inte har gått ut
`403`	Nyckeln har inte behörighet för denna resurs	Generera en ny nyckel med nödvändiga behörigheter

Andra fel

Kod	Beskrivning
`400`	Felaktiga parametrar eller saknade obligatoriska fält
`404`	Den begärda resursen existerar inte
`408`	Timeout för förfrågan (30 sekunder)
`413`	Förfrågans kropp överskrider 1 MB
`422`	Giltiga men ej bearbetbara data (t.ex. skatteprofil ej konfigurerad)
`429`	Förfrågningsgräns överskriden (försöks automatiskt igen)
`500`	Internt serverfel

Alla fel returnerar ett beskrivande tvåspråkigt meddelande (EN/ES) så att assistenten kan kommunicera problemet tydligt till användaren.

Begränsningar

Koncept	Värde
Förfrågningar per minut	100 per API-nyckel
Resultat per sida	100 max (50 som standard)
Förfrågans kropp	1 MB max
Webhook-payload	100 KB max
Webhooks per konto	20 max
Timeout för förfrågan	30 sekunder
Återförsök vid hastighetsbegränsning	3 max

Skillnad mot REST API

	MCP-server	REST API
Riktad till	AI-assistenter (Claude, Cursor, Windsurf)	Applikationer, skript, integrationer
Kommunikation	Naturligt språk via MCP-klienten	Direkt HTTP/JSON
Autentisering	Miljövariabel i klientkonfigurationen (eller OAuth)	Rubrik `X-API-Key` eller `Authorization: Bearer`
Format	Formaterad text + strukturerad utdata för assistenten	Rå JSON
Hastighetsbegränsning	Hanteras automatiskt (exponentiell backoff, 3 återförsök)	Manuellt (konsumenten måste implementera återförsök)
Observerbarhet	Strukturerad loggning + mått per verktyg	Förfrågningsloggar via `X-Request-Id`
Användningsfall	Prata med ditt ERP från IDE:n	Bygga programmatiska integrationer

Internt översätter MCP-servern varje verktygsanrop till en förfrågan till REST API:et. Den duplicerar inte logik — det är en tillståndslös brygga.

Utveckling

För att bidra eller köra servern i utvecklingsläge:

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

Kör lokalt:

FRIHET_API_KEY=fri_din_nyckel node dist/index.js

Kör med debug-loggar:

FRIHET_MCP_DEBUG=1 FRIHET_API_KEY=fri_din_nyckel node dist/index.js

Testa med MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

Relaterade resurser

API REST — Komplett referens för slutpunkter, autentisering och felkoder
Webhooks — Tillgängliga händelser, HMAC-SHA256-verifiering och återförsökspolicy
Färdighet för Claude Code — Affärsintelligenslager ovanpå MCP-servern
Källkod (GitHub) — MCP-serverns repository
Npm-paket — @frihet/mcp-server@1.5.1
MCP Registry — io.frihet/erp
Fjärr-slutpunkt — MCP-server hostad på Cloudflare Workers
MCP-specifikation — Protokolldokumentation

Föregående: Webhooks | Nästa: Färdighet för Claude Code

Vad du kan förvänta dig (och inte)​

Krav​

Hämta API-nyckeln​

Installation​

Universal (30+ agenter)​

MCP Registry​

Direkt npx​

Manuell konfiguration​

Lokal (stdio)​

Fjärr (streamable-http)​

Konfiguration per klient​

Miljövariabler​

OAuth-flöde​

Tillgängliga verktyg (44)​

Fakturor (6 verktyg)​

Utgifter (5 verktyg)​

Kunder (5 verktyg)​

Produkter (5 verktyg)​

Offerter (5 verktyg)​

Webhooks (5 verktyg)​

Tillgängliga resurser (8)​

Tillgängliga prompts (7)​

Användningsexempel​

Skapa en faktura​

Registrera en utgift​

Sök fakturor för en kund​

Konsultera förfallna fordringar​

Registrera en ny kund​

Konfigurera automatisering​

Uppdatera en produkt​

Observerbarhet​

Strukturerad loggning​

Verktygsmått​

Automatisk återförsök vid hastighetsbegränsning​

Transport​

Lokal (stdio)​

Fjärr (streamable-http)​

Felhantering​

Hastighetsbegränsning​

Autentiseringsfel​

Andra fel​

Begränsningar​

Skillnad mot REST API​

Utveckling​

Relaterade resurser​

Vad du kan förvänta dig (och inte)

Krav

Hämta API-nyckeln

Installation

Universal (30+ agenter)

MCP Registry

Direkt npx

Manuell konfiguration

Lokal (stdio)

Fjärr (streamable-http)

Konfiguration per klient

Miljövariabler

OAuth-flöde

Tillgängliga verktyg (44)

Fakturor (6 verktyg)

Utgifter (5 verktyg)

Kunder (5 verktyg)

Produkter (5 verktyg)

Offerter (5 verktyg)

Webhooks (5 verktyg)

Tillgängliga resurser (8)

Tillgängliga prompts (7)

Användningsexempel

Skapa en faktura

Registrera en utgift

Sök fakturor för en kund

Konsultera förfallna fordringar

Registrera en ny kund

Konfigurera automatisering

Uppdatera en produkt

Observerbarhet

Strukturerad loggning

Verktygsmått

Automatisk återförsök vid hastighetsbegränsning

Transport

Lokal (stdio)

Fjärr (streamable-http)

Felhantering

Hastighetsbegränsning

Autentiseringsfel

Andra fel

Begränsningar

Skillnad mot REST API

Utveckling

Relaterade resurser