io.github.jakobwennberg/fortnox MCP Server

Fortnox MCP Server

An MCP (Model Context Protocol) server for integrating with the Fortnox Swedish accounting system. This server enables LLMs to interact with Fortnox for managing invoices, customers, suppliers, orders, accounts, vouchers, and provides business intelligence analytics.

Two Ways to Use

Mode	Best For	Setup
Remote Mode	End users	Just add URL, authorize in browser
Local Mode	Developers, self-hosted	Configure environment variables

---

Quick Start: Remote Mode (Recommended)

The easiest way to use Fortnox MCP - no credentials needed, just authorize in your browser.

Option A: Add to Claude.ai (Web)

1. Go to claude.ai
2. Navigate to Settings → Integrations → Add Integration
3. Enter the URL: https://fortnox-mcp.vercel.app/mcp
4. Wait for it to load, then authorize access by clicking connect

Option B: Add to Claude Desktop

Open your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "fortnox": {
      "url": "https://fortnox-mcp.vercel.app/mcp"
    }
  }
}

Restart Claude Desktop. When you first ask Claude to do something with Fortnox, a browser window will open for you to authorize access to your Fortnox account. Once authorized, you're all set!

---

Quick Start: Local Mode (Self-Hosted)

For developers who want to run the server locally or use their own Fortnox app credentials.

1. Get your Fortnox credentials

1. Register at Fortnox Developer Portal
2. Create an application to get your Client ID and Client Secret
3. Complete the OAuth2 flow to get a Refresh Token

2. Add to Claude Desktop

Open your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "fortnox": {
      "command": "npx",
      "args": ["-y", "fortnox-mcp-server"],
      "env": {
        "FORTNOX_CLIENT_ID": "your-client-id",
        "FORTNOX_CLIENT_SECRET": "your-client-secret",
        "FORTNOX_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

3. Restart Claude Desktop

That's it! You can now ask Claude to manage your Fortnox invoices, customers, and more.

---

Features

Customer Management

• fortnox_list_customers - List and search customers
• fortnox_get_customer - Get customer details
• fortnox_create_customer - Create new customer
• fortnox_update_customer - Update customer
• fortnox_delete_customer - Delete customer

Invoice Management

• fortnox_list_invoices - List invoices with filtering
• fortnox_get_invoice - Get invoice details with line items
• fortnox_create_invoice - Create new invoice
• fortnox_update_invoice - Update draft invoice
• fortnox_bookkeep_invoice - Bookkeep invoice
• fortnox_cancel_invoice - Cancel invoice
• fortnox_credit_invoice - Create credit note
• fortnox_send_invoice_email - Send invoice by email

Supplier Management

• fortnox_list_suppliers - List and search suppliers
• fortnox_get_supplier - Get supplier details
• fortnox_create_supplier - Create new supplier
• fortnox_update_supplier - Update supplier
• fortnox_delete_supplier - Delete supplier

Supplier Invoice Management

• fortnox_list_supplier_invoices - List supplier invoices with filtering
• fortnox_get_supplier_invoice - Get supplier invoice details
• fortnox_approve_supplier_invoice - Approve supplier invoice for payment
• fortnox_payables_report - Get accounts payable aging report

Order Management

• fortnox_list_orders - List sales orders with filtering
• fortnox_list_offers - List offers/quotes with filtering

Account Management

• fortnox_list_accounts - List chart of accounts
• fortnox_get_account - Get account details
• fortnox_create_account - Create new account
• fortnox_update_account - Update account
• fortnox_delete_account - Delete account

Voucher Management

• fortnox_list_vouchers - List vouchers (journal entries)
• fortnox_get_voucher - Get voucher details with rows
• fortnox_create_voucher - Create manual voucher
• fortnox_list_voucher_series - List available voucher series
• fortnox_account_activity - Get activity for a specific account
• fortnox_search_vouchers - Search vouchers by description, account, or amount

Company Information

• fortnox_get_company_info - Get company details
• fortnox_list_financial_years - List company financial years

Analytics

• fortnox_invoice_summary - Get invoice statistics by period
• fortnox_top_customers - Get top customers by revenue
• fortnox_unpaid_report - Get detailed unpaid invoice report

Business Intelligence

• fortnox_cash_flow_forecast - Forecast cash flow based on invoices and payables
• fortnox_order_pipeline - Analyze sales order pipeline
• fortnox_sales_funnel - Analyze sales funnel from offers to invoices
• fortnox_product_performance - Analyze product/article performance
• fortnox_period_comparison - Compare financial metrics across periods
• fortnox_customer_growth - Analyze customer acquisition and growth
• fortnox_project_profitability - Analyze project profitability (if using projects)
• fortnox_cost_center_analysis - Analyze costs by cost center
• fortnox_expense_analysis - Analyze expenses by category
• fortnox_yearly_comparison - Compare year-over-year performance
• fortnox_gross_margin_trend - Track gross margin trends over time

Installation

Via npx (Recommended)

No installation needed! Just add the config above to Claude Desktop.

Manual Installation

npm install -g fortnox-mcp-server

From Source

git clone https://github.com/jakobwennberg/fortnox-mcp.git
cd fortnox-mcp
npm install
npm run build

Configuration

Environment Variables

Local Mode (default)

Variable	Required	Description
FORTNOX_CLIENT_ID	Yes	Your Fortnox app client ID
FORTNOX_CLIENT_SECRET	Yes	Your Fortnox app client secret
FORTNOX_REFRESH_TOKEN	Yes	OAuth2 refresh token (only needed for initial setup; automatically persisted after first use)
FORTNOX_ACCESS_TOKEN	No	Current access token (auto-refreshed)
TRANSPORT	No	stdio (default) or http
PORT	No	HTTP port (default: 3000)

Remote Mode (AUTH_MODE=remote)

Variable	Required	Description
AUTH_MODE	Yes	Set to remote
SERVER_URL	Yes	Public URL of your server
JWT_SECRET	Yes	Secret for signing JWT tokens
FORTNOX_CLIENT_ID	Yes	Your Fortnox app client ID
FORTNOX_CLIENT_SECRET	Yes	Your Fortnox app client secret
UPSTASH_REDIS_REST_URL	Yes*	Upstash Redis URL for token storage
UPSTASH_REDIS_REST_TOKEN	Yes*	Upstash Redis token
PORT	No	HTTP port (default: 3000)

*Falls back to in-memory storage if not provided (not recommended for production)

Getting OAuth Credentials

1. Register as a developer at Fortnox Developer Portal
2. Create a new application to get Client ID and Client Secret
3. Complete the OAuth2 authorization flow to obtain a refresh token
4. Set the environment variables

Usage

With Claude Desktop

See Quick Start above.

As HTTP Server

TRANSPORT=http PORT=3000 node dist/index.js

Then connect to http://localhost:3000/mcp

Tool Examples

List Unpaid Invoices

{
  "tool": "fortnox_list_invoices",
  "arguments": {
    "filter": "unpaid",
    "limit": 20
  }
}

Create Invoice

{
  "tool": "fortnox_create_invoice",
  "arguments": {
    "customer_number": "1001",
    "rows": [
      {
        "description": "Consulting services",
        "quantity": 10,
        "price": 1000
      }
    ]
  }
}

Create Voucher

{
  "tool": "fortnox_create_voucher",
  "arguments": {
    "voucher_series": "A",
    "description": "Office supplies",
    "transaction_date": "2025-01-24",
    "rows": [
      { "account_number": 6110, "debit": 500 },
      { "account_number": 1910, "credit": 500 }
    ]
  }
}

Rate Limiting

The Fortnox API allows 25 requests per 5 seconds. This server includes automatic rate limiting to prevent exceeding this limit.

Development

# Run in development mode with auto-reload
npm run dev

# Build for production
npm run build

# Clean build artifacts
npm run clean

Publishing & Distribution

This server is published to multiple registries for easy installation:

Registry	URL	Purpose
npm	npmjs.com/package/fortnox-mcp-server	Package distribution via npx
MCP Registry	registry.modelcontextprotocol.io	Official MCP server discovery
GitHub	github.com/jakobwennberg/fortnox-mcp	Source code

How It Works

1. User adds config to Claude Desktop with npx fortnox-mcp-server
2. Claude Desktop starts the server via npx (downloads latest version from npm)
3. Server authenticates with Fortnox using OAuth2 credentials from environment variables
4. Claude can now use tools like fortnox_list_invoices, fortnox_create_customer, etc.
5. Server handles API calls to Fortnox, including automatic token refresh and rate limiting

Token Persistence (Local Mode)

Fortnox refresh tokens are single-use — each token refresh returns a new one. The server automatically persists the latest refresh token to ~/.fortnox-mcp/tokens.json so it survives process restarts without requiring manual config updates.

• On first run, the server reads FORTNOX_REFRESH_TOKEN from your environment/config
• After each token refresh, the new refresh token is saved to ~/.fortnox-mcp/tokens.json
• On subsequent restarts, the server uses the persisted token (which is always the latest)
• If the persisted file is missing or corrupt, the server falls back to the environment variable

The token file is created with restricted permissions (0600) for security.

Releasing New Versions

To release a new version, use the release script:

# Bug fixes (1.0.0 → 1.0.1)
npm run release:patch

# New features (1.0.0 → 1.1.0)
npm run release:minor

# Breaking changes (1.0.0 → 2.0.0)
npm run release:major

The release script automatically:

1. Bumps the version in package.json
2. Updates server.json for the MCP Registry
3. Builds the project
4. Commits and tags the release
5. Publishes to npm
6. Publishes to MCP Registry
7. Pushes to GitHub

Prerequisites for releasing:

• npm login - Logged into npm
• mcp-publisher login github - Logged into MCP Registry
• Clean git working directory

Users Get Updates Automatically

When you publish a new version, users running npx -y fortnox-mcp-server will automatically get the latest version the next time they restart Claude Desktop.

---

Deploying Your Own Remote Server

Want to host your own instance of the Fortnox MCP server? Follow these instructions.

Deploy to Vercel

1. Prerequisites

• A Vercel account
• An Upstash Redis database (for token storage)
• A Fortnox Developer account with an app created

2. Set Environment Variables

In your Vercel project settings, add these environment variables:

Variable	Description
AUTH_MODE	Set to remote
SERVER_URL	Your Vercel deployment URL (e.g., https://your-app.vercel.app)
JWT_SECRET	A random secret string for signing tokens (generate with openssl rand -hex 32)
FORTNOX_CLIENT_ID	Your Fortnox app client ID
FORTNOX_CLIENT_SECRET	Your Fortnox app client secret
UPSTASH_REDIS_REST_URL	Upstash Redis REST URL
UPSTASH_REDIS_REST_TOKEN	Upstash Redis REST token

3. Configure Fortnox OAuth Callback

In your Fortnox app settings, add this redirect URI:

https://your-app.vercel.app/oauth/fortnox/callback

4. Deploy

vercel --prod

Server Endpoints

Endpoint	Description
GET /health	Health check
GET /.well-known/oauth-authorization-server	OAuth metadata
POST /authorize	Start OAuth flow
POST /token	Exchange code for tokens
GET /oauth/fortnox/callback	Fortnox OAuth callback
POST /mcp	Protected MCP endpoint

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    fortnox-mcp-server                       │
├─────────────────────────────────────────────────────────────┤
│   Mode: AUTH_MODE=local | remote                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│   LOCAL MODE                    REMOTE MODE                 │
│   ───────────                   ───────────                 │
│   • Env var tokens              • OAuth flow                │
│   • Single user                 • Multi-user                │
│   • stdio or HTTP               • HTTP only                 │
│   • Auto-persisted tokens       • Token storage (Redis)     │
│     (~/.fortnox-mcp/)                                       │
│                                                             │
└─────────────────────────────────────────────────────────────┘

License

MIT