Fortnox MCP

🚀 Fortnox MCP 服務器

這是一個用於集成瑞典 Fortnox 會計系統的 MCP（模型上下文協議）服務器。該服務器使大語言模型（LLMs）能夠與 Fortnox 進行交互，以管理發票、客戶、供應商、訂單、賬戶、憑證等，並提供商業智能分析。

🚀 快速開始

兩種使用方式

遠程模式（推薦）

這是使用 Fortnox MCP 最簡單的方法，無需憑證，只需在瀏覽器中授權。

選項 A：添加到 Claude.ai（網頁版）

1. 訪問 claude.ai
2. 導航至 設置 → 集成 → 添加集成
3. 輸入 URL：https://fortnox-mcp.vercel.app/mcp
4. 等待加載完成，點擊“連接”授權訪問

選項 B：添加到 Claude 桌面版

打開 Claude 桌面版配置文件：

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

添加以下配置：

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

重啟 Claude 桌面版。當你首次要求 Claude 對 Fortnox 執行操作時，會打開一個瀏覽器窗口，用於授權訪問你的 Fortnox 賬戶。授權完成後即可使用！

本地模式（自託管）

適用於希望在本地運行服務器或使用自己的 Fortnox 應用憑證的開發者。

1. 獲取 Fortnox 憑證

1. 在 Fortnox 開發者門戶 註冊
2. 創建一個應用程序，獲取 客戶端 ID 和 客戶端密鑰
3. 完成 OAuth2 流程，獲取 刷新令牌

2. 添加到 Claude 桌面版

打開 Claude 桌面版配置文件：

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

添加以下配置：

{
  "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. 重啟 Claude 桌面版

完成！你現在可以要求 Claude 管理你的 Fortnox 發票、客戶等。

✨ 主要特性

客戶管理

• fortnox_list_customers - 列出並搜索客戶
• fortnox_get_customer - 獲取客戶詳情
• fortnox_create_customer - 創建新客戶
• fortnox_update_customer - 更新客戶信息
• fortnox_delete_customer - 刪除客戶

發票管理

• fortnox_list_invoices - 按條件列出發票
• fortnox_get_invoice - 獲取包含行項目的發票詳情
• fortnox_create_invoice - 創建新發票
• fortnox_update_invoice - 更新草稿發票
• fortnox_bookkeep_invoice - 記賬發票
• fortnox_cancel_invoice - 取消發票
• fortnox_credit_invoice - 創建貸項通知單
• fortnox_send_invoice_email - 通過電子郵件發送發票

供應商管理

• fortnox_list_suppliers - 列出並搜索供應商
• fortnox_get_supplier - 獲取供應商詳情
• fortnox_create_supplier - 創建新供應商
• fortnox_update_supplier - 更新供應商信息
• fortnox_delete_supplier - 刪除供應商

供應商發票管理

• fortnox_list_supplier_invoices - 按條件列出供應商發票
• fortnox_get_supplier_invoice - 獲取供應商發票詳情
• fortnox_approve_supplier_invoice - 批准供應商發票付款
• fortnox_payables_report - 獲取應付賬款賬齡報告

訂單管理

• fortnox_list_orders - 按條件列出銷售訂單
• fortnox_list_offers - 按條件列出報價/報價單

賬戶管理

• fortnox_list_accounts - 列出會計科目表
• fortnox_get_account - 獲取賬戶詳情
• fortnox_create_account - 創建新賬戶
• fortnox_update_account - 更新賬戶信息
• fortnox_delete_account - 刪除賬戶

憑證管理

• fortnox_list_vouchers - 列出憑證（日記賬分錄）
• fortnox_get_voucher - 獲取包含行項目的憑證詳情
• fortnox_create_voucher - 創建手動憑證
• fortnox_list_voucher_series - 列出可用的憑證系列
• fortnox_account_activity - 獲取特定賬戶的活動情況
• fortnox_search_vouchers - 按描述、賬戶或金額搜索憑證

公司信息

• fortnox_get_company_info - 獲取公司詳情
• fortnox_list_financial_years - 列出公司財政年度

分析

• fortnox_invoice_summary - 按時間段獲取發票統計信息
• fortnox_top_customers - 按收入獲取頂級客戶
• fortnox_unpaid_report - 獲取詳細的未付發票報告

商業智能

• fortnox_cash_flow_forecast - 根據發票和應付賬款預測現金流
• fortnox_order_pipeline - 分析銷售訂單管道
• fortnox_sales_funnel - 分析從報價到發票的銷售漏斗
• fortnox_product_performance - 分析產品/商品性能
• fortnox_period_comparison - 跨時間段比較財務指標
• fortnox_customer_growth - 分析客戶獲取和增長情況
• fortnox_project_profitability - 分析項目盈利能力（如果使用項目）
• fortnox_cost_center_analysis - 按成本中心分析成本
• fortnox_expense_analysis - 按類別分析費用
• fortnox_yearly_comparison - 比較年度業績
• fortnox_gross_margin_trend - 跟蹤毛利率趨勢

📦 安裝指南

通過 npx（推薦）

無需安裝！只需將上述配置添加到 Claude 桌面版即可。

手動安裝

npm install -g fortnox-mcp-server

從源代碼安裝

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

📚 詳細文檔

配置

環境變量

本地模式（默認）

遠程模式（AUTH_MODE=remote）

*如果未提供，將回退到內存存儲（不建議用於生產環境）

獲取 OAuth 憑證

1. 在 Fortnox 開發者門戶 註冊為開發者
2. 創建一個新應用程序，獲取客戶端 ID 和客戶端密鑰
3. 完成 OAuth2 授權流程，獲取刷新令牌
4. 設置環境變量

使用方法

與 Claude 桌面版一起使用

請參閱上面的 快速開始 部分。

作為 HTTP 服務器使用

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

然後連接到 http://localhost:3000/mcp

💻 使用示例

列出未付發票

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

創建發票

{
  "tool": "fortnox_create_invoice",
  "arguments": {
    "customer_number": "1001",
    "rows": [
      {
        "description": "諮詢服務",
        "quantity": 10,
        "price": 1000
      }
    ]
  }
}

創建憑證

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

速率限制

Fortnox API 允許每 5 秒進行 25 次請求。此服務器包含自動速率限制，以防止超過此限制。

開發

# 在開發模式下運行，支持自動重新加載
npm run dev

# 為生產環境構建
npm run build

# 清理構建工件
npm run clean

發佈與分發

此服務器已發佈到多個註冊表，以便於安裝：

工作原理

1. 用戶將配置添加到 Claude 桌面版，使用 npx fortnox-mcp-server
2. Claude 桌面版通過 npx 啟動服務器（從 npm 下載最新版本）
3. 服務器使用環境變量中的 OAuth2 憑證進行身份驗證 與 Fortnox
4. Claude 現在可以使用工具，如 fortnox_list_invoices、fortnox_create_customer 等
5. 服務器處理對 Fortnox 的 API 調用，包括自動令牌刷新和速率限制

發佈新版本

要發佈新版本，請使用發佈腳本：

# 修復 bug（1.0.0 → 1.0.1）
npm run release:patch

# 添加新特性（1.0.0 → 1.1.0）
npm run release:minor

# 重大更改（1.0.0 → 2.0.0）
npm run release:major

發佈腳本會自動執行以下操作：

1. 在 package.json 中提升版本號
2. 更新 MCP 註冊表的 server.json
3. 構建項目
4. 提交併標記發佈
5. 發佈到 npm
6. 發佈到 MCP 註冊表
7. 推送到 GitHub

發佈前提條件：

• npm login - 已登錄到 npm
• mcp-publisher login github - 已登錄到 MCP 註冊表
• 乾淨的 git 工作目錄

用戶自動獲取更新

當你發佈新版本時，運行 npx -y fortnox-mcp-server 的用戶下次重啟 Claude 桌面版時將自動獲取最新版本。

部署自己的遠程服務器

如果你想託管自己的 Fortnox MCP 服務器實例，請按照以下說明操作。

部署到 Vercel

1. 前提條件

• 一個 Vercel 賬戶
• 一個 Upstash Redis 數據庫（用於令牌存儲）
• 一個 Fortnox 開發者 賬戶，並創建了一個應用程序

2. 設置環境變量

在你的 Vercel 項目設置中，添加以下環境變量：

3. 配置 Fortnox OAuth 回調

在你的 Fortnox 應用設置中，添加以下重定向 URI：

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

4. 部署

vercel --prod

服務器端點

架構

┌─────────────────────────────────────────────────────────────┐
│                    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                 │
│                                 • Token storage (Redis)     │
│                                                             │
└─────────────────────────────────────────────────────────────┘

📄 許可證

MIT