### Local Installation of Frihet MCP Server Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Installs the Frihet MCP server locally using npx. Requires setting the FRIHET_API_KEY environment variable for authentication. ```json { "mcpServers": { "frihet": { "command": "npx", "args": ["-y", "@frihet/mcp-server"], "env": { "FRIHET_API_KEY": "fri_your_key_here" } } } } ``` -------------------------------- ### Install Frihet Claude Code Skill Source: https://github.com/frihet-io/frihet-mcp/blob/main/README.md Instructions for cloning the repository and creating a symbolic link to install the Frihet Claude Code skill locally. This skill adds business context like Spanish tax rules and workflow recipes. ```bash git clone https://github.com/Frihet-io/frihet-mcp.git ln -s $(pwd)/frihet-mcp/skill ~/.claude/skills/frihet ``` ```bash npx skills add Frihet-io/frihet-mcp ``` -------------------------------- ### npm postinstall Script for Star CTA Source: https://github.com/frihet-io/frihet-mcp/blob/main/STARS_STRATEGY.md This JSON snippet shows how to add a 'postinstall' script to the package.json file. It displays a message to users after installation, prompting them to star the GitHub repository. ```json "scripts": { "postinstall": "echo '\n Frihet MCP Server installed. 31 tools ready.\n Like it? Star us: https://github.com/Frihet-io/frihet-mcp\n'" } ``` -------------------------------- ### REST API: Pagination (Bash) Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Explains how to paginate through results for resources like expenses. It shows examples for both offset-based pagination (using limit and offset) and cursor-based pagination (using 'after' parameter). ```bash # First page curl "https://api.frihet.io/v1/expenses?limit=50&offset=0" # Second page curl "https://api.frihet.io/v1/expenses?limit=50&offset=50" # Cursor-based pagination curl "https://api.frihet.io/v1/expenses?limit=50&after=exp_lastid" ``` -------------------------------- ### Add Repository Meta to Tool Responses Source: https://github.com/frihet-io/frihet-mcp/blob/main/STARS_STRATEGY.md This JSON example demonstrates adding a '_meta' field to the structured output of each tool. This field includes server information and a link to the GitHub repository, which might be surfaced by AI assistants. ```json { "data": {...}, "_meta": { "server": "frihet-mcp", "repo": "https://github.com/Frihet-io/frihet-mcp" } } ``` -------------------------------- ### REST API: List Invoices with Filters (Bash) Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Demonstrates how to retrieve a list of invoices with filtering capabilities. This example shows how to filter by status (e.g., 'overdue') and limit the number of results returned. ```bash curl -X GET "https://api.frihet.io/v1/invoices?status=overdue&limit=20" \ -H "X-API-Key: fri_your_key_here" ``` -------------------------------- ### Execute Monthly Close Prompt (JSON) Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Initiates the monthly closing process. This prompt guides users through reviewing unpaid invoices, categorizing expenses, checking tax obligations, and generating a financial summary. The month can be optionally specified. ```json { "prompt": "monthly-close", "arguments": { "month": "2026-03" // Optional, defaults to previous month } } ``` -------------------------------- ### Get Business Context Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Retrieves the complete business context for the current session, including profile, plan limits, recent activity, and financial summaries. This should be called first. ```APIDOC ## GET /api/business_context ### Description Gets complete business context—profile, defaults, plan limits, recent activity, top clients, and current month summary. Call this FIRST in any session to understand the user's business. ### Method GET ### Endpoint /api/business_context ### Parameters #### Query Parameters None ### Request Example ```json { "tool": "get_business_context", "arguments": {} } ``` ### Response #### Success Response (200) - **business** (object) - Company details including name, tax ID, fiscal zone, default tax rate, and currency. - **plan** (string) - The current subscription plan. - **limits** (object) - Usage limits for various features like invoices and AI messages. - **usage** (object) - Current usage statistics for the month/day. - **recentActivity** (array) - A list of recent significant events. - **topClients** (array) - A list of top clients by revenue. - **currentMonth** (object) - Financial summary for the current month (revenue, expenses, profit). #### Response Example ```json { "business": { "name": "Freelance Studio", "taxId": "12345678A", "fiscalZone": "peninsula", "defaultTaxRate": 21, "currency": "EUR" }, "plan": "professional", "limits": { "invoicesPerMonth": 100, "aiMessagesPerDay": 50, "teamMembers": 5 }, "usage": { "invoicesThisMonth": 12, "aiMessagesToday": 8 }, "recentActivity": [ { "type": "invoice.created", "description": "Invoice INV-2026-089", "at": "2026-03-15T10:30:00Z" } ], "topClients": [ { "name": "TechStart SL", "totalRevenue": 45000, "invoiceCount": 12 } ], "currentMonth": { "revenue": 12500, "expenses": 3200, "profit": 9300 } } ``` ``` -------------------------------- ### Frihet MCP Skill Commands Source: https://github.com/frihet-io/frihet-mcp/blob/main/skill/SKILL.md Examples of commands to interact with the Frihet MCP Skill for various business management tasks. These commands cover status checks, invoice and expense management, client database operations, quote creation, financial reporting, and webhook configuration. ```bash /frihet status /frihet invoice "Acme 3500 EUR consulting enero" /frihet expense "47.50 gasolina 15 feb" /frihet clients "Acme" /frihet quote create /frihet report quarterly /frihet webhooks /frihet setup ``` -------------------------------- ### Remote Installation of Frihet MCP Server Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Connects to the Frihet MCP server via a remote, hosted endpoint. This method requires an Authorization header with a Bearer token. ```json { "mcpServers": { "frihet": { "type": "streamable-http", "url": "https://mcp.frihet.io/mcp", "headers": { "Authorization": "Bearer fri_your_key_here" } } } } ``` -------------------------------- ### Get Product by ID - Frihet MCP API Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Fetches details for a specific product or service using its unique identifier. Essential for retrieving individual product information. ```typescript { "tool": "get_product", "arguments": { "id": "prod_123" } } ``` -------------------------------- ### Execute Onboard Client Prompt (JSON) Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Sets up a new client record, determines appropriate tax rates based on location, and optionally creates a welcome quote. Client name, country, and region are required arguments. ```json { "prompt": "onboard-client", "arguments": { "clientName": "New Tech SL", "country": "ES", "region": "peninsula" } } ``` -------------------------------- ### MCP Prompt: onboard-client Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Workflow to register a new client and configure their tax settings. ```APIDOC ## Prompt: onboard-client ### Description Automates the creation of a new client record and determines tax rates based on location. ### Parameters - **clientName** (string) - Required - Name of the client - **country** (string) - Required - ISO country code - **region** (string) - Required - Fiscal region (e.g., peninsula) ### Request Example { "prompt": "onboard-client", "arguments": { "clientName": "New Tech SL", "country": "ES", "region": "peninsula" } } ``` -------------------------------- ### GET /invoices Source: https://github.com/frihet-io/frihet-mcp/blob/main/README.md Retrieves a paginated list of invoices from the system. ```APIDOC ## GET /invoices ### Description Retrieves a paginated list of all invoices. Supports filtering and sorting via query parameters. ### Method GET ### Endpoint /invoices ### Parameters #### Query Parameters - **limit** (integer) - Optional - Number of records to return. - **offset** (integer) - Optional - Pagination offset. ### Response #### Success Response (200) - **data** (array) - List of invoice objects. - **total** (integer) - Total count of invoices. #### Response Example { "data": [{"id": "inv_001", "amount": 150.00}], "total": 1, "limit": 10, "offset": 0 } ``` -------------------------------- ### Execute Quarterly Tax Prep Prompt (JSON) Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Prepares data for quarterly tax filing. It lists invoices and expenses, calculates VAT/IGIC, identifies deductible expenses, and generates a preview for tax forms like Modelo 303/130/420. The quarter and fiscal zone can be specified. ```json { "prompt": "quarterly-tax-prep", "arguments": { "quarter": "Q1 2026", "fiscalZone": "peninsula" // Optional: peninsula, canarias, ceuta, melilla } } ``` -------------------------------- ### GET /invoices Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Retrieve a list of invoices with support for filtering by status and pagination. ```APIDOC ## GET /invoices ### Description Retrieves a list of invoices. Supports filtering by status and pagination via query parameters. ### Method GET ### Endpoint https://api.frihet.io/v1/invoices ### Parameters #### Query Parameters - **status** (string) - Optional - Filter by invoice status (e.g., overdue, paid) - **limit** (integer) - Optional - Number of records to return - **offset** (integer) - Optional - Number of records to skip ### Request Example curl -X GET "https://api.frihet.io/v1/invoices?status=overdue&limit=20" -H "X-API-Key: your_key" ### Response #### Success Response (200) - **invoices** (array) - List of invoice objects #### Response Example { "invoices": [ { "id": "inv_123", "status": "overdue", "amount": 1500 } ] } ``` -------------------------------- ### Get Expense - TypeScript Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Fetches details for a single expense identified by its unique ID. ```typescript { "tool": "get_expense", "arguments": { "id": "exp_123" } } ``` -------------------------------- ### REST API: Base URL and Authentication (Bash) Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Demonstrates how to set the base URL for the Frihet API and authenticate requests using an API key in the request header. This is a prerequisite for all API interactions. ```bash # Base URL https://api.frihet.io/v1 # Authentication via header curl -X GET "https://api.frihet.io/v1/invoices" \ -H "X-API-Key: fri_your_key_here" \ -H "Content-Type: application/json" ``` -------------------------------- ### Get Monthly Summary Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Retrieves a detailed financial summary for a specified month, including revenue, expenses, profit, and tax information. ```APIDOC ## GET /api/monthly_summary ### Description Gets complete monthly financial summary—revenue, expenses, profit, tax liability, invoice stats, expense breakdown by category. ### Method GET ### Endpoint /api/monthly_summary ### Parameters #### Query Parameters - **month** (string) - Required - The month in 'YYYY-MM' format (e.g., '2026-03'). ### Request Example ```json { "tool": "get_monthly_summary", "arguments": { "month": "2026-03" } } ``` ### Response #### Success Response (200) - **month** (string) - The month for which the summary is provided. - **revenue** (object) - Revenue details including total, tax collected, and invoice count. - **expenses** (object) - Expense details including total, tax deductible amount, and breakdown by category. - **profit** (number) - The calculated profit for the month. - **taxLiability** (object) - Estimated tax liabilities (VAT, IRPF). #### Response Example ```json { "month": "2026-03", "revenue": { "total": 15000, "taxCollected": 3150, "invoiceCount": 8 }, "expenses": { "total": 2500, "taxDeductible": 525, "byCategory": { "software": 500, "travel": 800, "office": 300, "professional": 900 } }, "profit": 12500, "taxLiability": { "vatOwed": 2625, "irpfEstimate": 2500 } } ``` ``` -------------------------------- ### Get Invoice PDF - TypeScript Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Retrieves the download URL for an invoice's PDF. Includes filename and expiration time for the URL. ```typescript { "tool": "get_invoice_pdf", "arguments": { "id": "inv_abc123" } } ``` -------------------------------- ### Execute New Client Invoice Prompt (JSON) Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Creates a new client and their first invoice simultaneously. This prompt handles tax rate lookups based on the client's country, considering regulations like EU reverse charge. ```json { "prompt": "new-client-invoice", "arguments": { "clientName": "Global Corp", "country": "DE" // Germany - EU reverse charge applies } } ``` -------------------------------- ### Get Quarterly Taxes Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Retrieves quarterly tax preparation data, including details for Modelo 303 and Modelo 130, and filing deadlines. ```APIDOC ## GET /api/quarterly_taxes ### Description Gets quarterly tax preparation data—Modelo 303 (IVA/IGIC), Modelo 130 (IRPF income tax advance), revenue/expense totals, tax collected vs deductible. ### Method GET ### Endpoint /api/quarterly_taxes ### Parameters #### Query Parameters - **quarter** (string) - Required - The quarter in 'YYYY-Q#' format (e.g., '2026-Q1'). ### Request Example ```json { "tool": "get_quarterly_taxes", "arguments": { "quarter": "2026-Q1" } } ``` ### Response #### Success Response (200) - **quarter** (string) - The quarter for which the data is provided. - **fiscalZone** (string) - The applicable fiscal zone (e.g., 'peninsula'). - **modelo303** (object) - Details for Modelo 303 (VAT/IGIC). - **modelo130** (object) - Details for Modelo 130 (IRPF income tax advance). - **filingDeadline** (string) - The deadline for filing the taxes. #### Response Example ```json { "quarter": "2026-Q1", "fiscalZone": "peninsula", "modelo303": { "baseImponible": 45000, "ivaRepercutido": 9450, "ivaSoportado": 1575, "resultado": 7875 }, "modelo130": { "ingresos": 45000, "gastos": 7500, "rendimientoNeto": 37500, "pagoFraccionado": 7500 }, "filingDeadline": "2026-04-20" } ``` ``` -------------------------------- ### Get Client by ID - Frihet MCP API Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Fetches details for a specific client using their unique identifier. This is essential for retrieving individual client information. ```typescript { "tool": "get_client", "arguments": { "id": "cli_abc123" } } ``` -------------------------------- ### Create Product - Frihet MCP API Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Adds a new product or service to the catalog. Requires a name, unit price, and optionally includes description and tax rate. ```typescript { "tool": "create_product", "arguments": { "name": "Web Development", "description": "Full-stack web development services", "unitPrice": 120.00, "taxRate": 21 } } ``` -------------------------------- ### Get Invoice Tool Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Retrieves the full details of a single invoice using its ID. The response includes all line items, totals, tax breakdown, and status. ```typescript // Get invoice details { "tool": "get_invoice", "arguments": { "id": "inv_abc123" } } // Response { "id": "inv_abc123", "documentNumber": "INV-2026-089", "clientName": "TechStart SL", "clientId": "cli_xyz789", "status": "sent", "issueDate": "2026-03-15", "dueDate": "2026-04-15", "items": [ { "description": "Consulting services - March 2026", "quantity": 40, "unitPrice": 75 } ], "subtotal": 3000.00, "taxRate": 21, "taxAmount": 630.00, "total": 3630.00, "notes": "Payment due within 30 days", "createdAt": "2026-03-15T10:30:00Z", "updatedAt": "2026-03-15T10:30:00Z" } ``` -------------------------------- ### Access MCP Resources Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Demonstrates how to read various configuration and reference resources from the MCP server using the mcp.readResource method. ```typescript const schema = await mcp.readResource("frihet://api/schema"); const taxRates = await mcp.readResource("frihet://tax/rates"); const calendar = await mcp.readResource("frihet://tax/calendar"); const categories = await mcp.readResource("frihet://config/expense-categories"); const statuses = await mcp.readResource("frihet://config/invoice-statuses"); const profile = await mcp.readResource("frihet://business-profile"); ``` -------------------------------- ### Get Invoice eInvoice - TypeScript Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Downloads the e-invoice XML for a given invoice. Supports multiple formats including UBL, CII, XRechnung, Factur-X, FatturaPA, and PEPPOL. ```typescript { "tool": "get_invoice_einvoice", "arguments": { "id": "inv_abc123" } } ``` -------------------------------- ### Create Client - Frihet MCP API Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Adds a new client to the system. Requires at least a name and can include contact details, tax IDs, and addresses. Used for onboarding new customers. ```typescript { "tool": "create_client", "arguments": { "name": "Acme Corporation SL", "email": "billing@acme.com", "phone": "+34 600 987 654", "taxId": "B87654321", "address": { "street": "Gran Vía 42", "city": "Madrid", "postalCode": "28013", "country": "ES" } } } ``` -------------------------------- ### REST API: Create Invoice (Bash) Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Shows how to create a new invoice using a POST request to the '/invoices' endpoint. It includes required fields like client name, items, tax rate, and due date in the request body. ```bash curl -X POST "https://api.frihet.io/v1/invoices" \ -H "X-API-Key: fri_your_key_here" \ -H "Content-Type: application/json" \ -d '{ "clientName": "Acme Corp SL", "items": [ {"description": "Consulting services", "quantity": 40, "unitPrice": 75} ], "taxRate": 21, "dueDate": "2026-04-15" }' ``` -------------------------------- ### Add Support Call-to-Action Source: https://github.com/frihet-io/frihet-mcp/blob/main/STARS_STRATEGY.md A Markdown snippet designed to encourage users to star the repository if they find the project valuable, helping to improve social proof. ```markdown ## Support If Frihet MCP saves you time, [star the repo](https://github.com/Frihet-io/frihet-mcp) -- it helps others discover it. ``` -------------------------------- ### POST create_client Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Creates a new client record in the system, which is required for generating invoices and quotes. ```APIDOC ## POST create_client ### Description Creates a new client/customer. Requires at minimum a name. ### Method POST ### Endpoint create_client ### Parameters #### Request Body - **name** (string) - Required - Client name - **email** (string) - Optional - Contact email - **taxId** (string) - Optional - Tax identification number ### Request Example { "tool": "create_client", "arguments": { "name": "Acme Corporation SL", "email": "billing@acme.com" } } ``` -------------------------------- ### Retrieve Business Context Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Fetches the complete business profile, including plan limits, recent activity, and financial summaries. This should be the initial call in any session to establish context. ```json { "tool": "get_business_context", "arguments": {} } ``` -------------------------------- ### MCP Resource: frihet://monthly-snapshot Source: https://context7.com/frihet-io/frihet-mcp/llms.txt Access real-time financial summary data for the current month. ```APIDOC ## Resource: frihet://monthly-snapshot ### Description Provides a live financial snapshot for the current month including revenue, expenses, profit, and tax liability. ### Method GET (via MCP readResource) ### Endpoint frihet://monthly-snapshot ### Response #### Success Response (200) - **revenue** (number) - Total revenue - **expenses** (number) - Total expenses - **profit** (number) - Net profit - **taxLiability** (number) - Current tax owed ``` -------------------------------- ### Update Server Startup Message Source: https://github.com/frihet-io/frihet-mcp/blob/main/STARS_STRATEGY.md This TypeScript code modifies the server startup message to include the version and a direct link to the GitHub repository, displayed on stderr. This ensures users see the star request even when running the server. ```typescript console.error("Frihet MCP server running on stdio (v1.2.4, 31 tools)"); console.error("Star us: https://github.com/Frihet-io/frihet-mcp"); ``` -------------------------------- ### Embed Demo GIF in Markdown Source: https://github.com/frihet-io/frihet-mcp/blob/main/STARS_STRATEGY.md This snippet provides the HTML structure to center and display a demonstration GIF within a Markdown file, ensuring optimal visibility for repository visitors. ```markdown