fortnox-mcp

🚀 Fortnox MCP 服务器

这是一个用于集成瑞典 Fortnox 会计系统的 MCP（模型上下文协议）服务器。该服务器使大语言模型（LLMs）能够与 Fortnox 进行交互，以管理发票、客户、供应商、订单、账户、凭证等，并提供商业智能分析。

🚀 快速开始

两种使用方式

| 模式 | 适用人群 | 设置方式 | |------|----------|-------| | 远程模式 | 终端用户 | 只需添加 URL，在浏览器中授权 | | 本地模式 | 开发者、自托管用户 | 配置环境变量 |

远程模式（推荐）

这是使用 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

📚 详细文档

配置

环境变量

本地模式（默认）

| 变量 | 是否必需 | 描述 | |----------|----------|-------------| | FORTNOX_CLIENT_ID | 是 | 你的 Fortnox 应用客户端 ID | | FORTNOX_CLIENT_SECRET | 是 | 你的 Fortnox 应用客户端密钥 | | FORTNOX_REFRESH_TOKEN | 是 | OAuth2 刷新令牌 | | FORTNOX_ACCESS_TOKEN | 否 | 当前访问令牌（自动刷新） | | TRANSPORT | 否 | stdio（默认）或 http | | PORT | 否 | HTTP 端口（默认：3000） |

远程模式（AUTH_MODE=remote）

| 变量 | 是否必需 | 描述 | |----------|----------|-------------| | AUTH_MODE | 是 | 设置为 remote | | SERVER_URL | 是 | 服务器的公共 URL | | JWT_SECRET | 是 | 用于签署 JWT 令牌的密钥 | | FORTNOX_CLIENT_ID | 是 | 你的 Fortnox 应用客户端 ID | | FORTNOX_CLIENT_SECRET | 是 | 你的 Fortnox 应用客户端密钥 | | UPSTASH_REDIS_REST_URL | 是* | 用于令牌存储的 Upstash Redis URL | | UPSTASH_REDIS_REST_TOKEN | 是* | Upstash Redis 令牌 | | PORT | 否 | HTTP 端口（默认：3000） |

*如果未提供，将回退到内存存储（不建议用于生产环境）

获取 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

发布与分发

此服务器已发布到多个注册表，以便于安装： | 注册表 | URL | 用途 | |----------|-----|---------| | npm | npmjs.com/package/fortnox-mcp-server | 通过 npx 进行包分发 | | MCP 注册表 | registry.modelcontextprotocol.io | 官方 MCP 服务器发现 | | GitHub | github.com/jakobwennberg/fortnox-mcp | 源代码 |

工作原理

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 项目设置中，添加以下环境变量： | 变量 | 描述 | |----------|-------------| | AUTH_MODE | 设置为 remote | | SERVER_URL | 你的 Vercel 部署 URL（例如，https://your-app.vercel.app） | | JWT_SECRET | 用于签署令牌的随机密钥字符串（使用 openssl rand -hex 32 生成） | | FORTNOX_CLIENT_ID | 你的 Fortnox 应用客户端 ID | | FORTNOX_CLIENT_SECRET | 你的 Fortnox 应用客户端密钥 | | UPSTASH_REDIS_REST_URL | Upstash Redis REST URL | | UPSTASH_REDIS_REST_TOKEN | Upstash Redis REST 令牌 |

3. 配置 Fortnox OAuth 回调

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

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

4. 部署

vercel --prod

服务器端点

| 端点 | 描述 | |----------|-------------| | GET /health | 健康检查 | | GET /.well-known/oauth-authorization-server | OAuth 元数据 | | POST /authorize | 启动 OAuth 流程 | | POST /token | 用代码交换令牌 | | GET /oauth/fortnox/callback | Fortnox OAuth 回调 | | POST /mcp | 受保护的 MCP 端点 |

架构

┌─────────────────────────────────────────────────────────────┐
│                    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