Freee MCP

用于免费记账的MCP服务器API

模型上下文协议（MCP）服务器，提供与免费会计软件API的集成，使人工智能助手能够与会计数据交互。

特性

• OAuth 2.0身份验证流支持
• 公司管理层
• 交易（交易）操作
• 账户项目管理
• 合作伙伴管理
• 章节和标签
• 发票创建和管理
• 试算表报告
• 令牌持久化和自动刷新

先决条件

• Node.js 20或更高版本
• 免费API凭据（客户端ID和客户端机密）
• 具有API访问权限的免费帐户

快速开始

选择以下方法之一开始：

选项A:npx（无需本地构建）

将以下内容添加到您的Claude Desktop配置中(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS或 %APPDATA%\Claude\claude_desktop_config.json 在Windows上）：

{
  "mcpServers": {
    "freee": {
      "command": "npx",
      "args": ["-y", "github:knishioka/freee-mcp"],
      "env": {
        "FREEE_CLIENT_ID": "your_client_id",
        "FREEE_CLIENT_SECRET": "your_client_secret",
        "FREEE_TOKEN_ENCRYPTION_KEY": "replace-with-strong-random-value"
      }
    }
  }
}

备注：首次发射 npx 下载依赖项和编译TypeScript可能需要30-60秒。后续发射将更快。

选项B：本地构建

git clone https://github.com/knishioka/freee-mcp.git
cd freee-mcp
npm install && npm run build

{
  "mcpServers": {
    "freee": {
      "command": "node",
      "args": ["/absolute/path/to/freee-mcp/dist/index.js"],
      "env": {
        "FREEE_CLIENT_ID": "your_client_id",
        "FREEE_CLIENT_SECRET": "your_client_secret",
        "FREEE_TOKEN_ENCRYPTION_KEY": "replace-with-strong-random-value"
      }
    }
  }
}

请参阅 安装 详细的设置说明，包括环境变量和其他MCP客户端配置。

我应该使用哪种方法？

安装

1. 克隆存储库：

git clone https://github.com/knishioka/freee-mcp.git
cd freee-mcp

1. 安装依赖项：

npm install

1. 构建TypeScript代码：

npm run build

1. 复制环境示例文件并对其进行配置：

cp .env.example .env

1. 编辑 .env 使用您的免费API证书：

FREEE_CLIENT_ID=your_client_id_here
FREEE_CLIENT_SECRET=your_client_secret_here
FREEE_REDIRECT_URI=urn:ietf:wg:oauth:2.0:oob
# TOKEN_STORAGE_PATH=./tokens.enc  # Optional: defaults to platform-specific secure path

配置

获取免费API凭据

1. 登录您的freee帐户
2. 去 freee应用商店
3. 创建新应用程序
4. 记下客户端ID和客户端密码
5. 设置重定向URI（使用 urn:ietf:wg:oauth:2.0:oob 地方发展）

MCP客户端配置

先构建服务器(npm run build)，然后配置下面的一个客户端。

环境变量

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json or %APPDATA%\\Claude\\claude_desktop_config.json)

{
  "mcpServers": {
    "freee": {
      "command": "node",
      "args": ["/absolute/path/to/freee-mcp/dist/index.js"],
      "env": {
        "FREEE_CLIENT_ID": "your_client_id_here",
        "FREEE_CLIENT_SECRET": "your_client_secret_here",
        "TOKEN_STORAGE_PATH": "/absolute/path/to/freee-mcp/tokens.enc",
        "FREEE_DEFAULT_COMPANY_ID": "123456",
        "FREEE_TOKEN_ENCRYPTION_KEY": "replace-with-strong-random-value"
      }
    }
  }
}

Claude Code CLI

claude mcp add freee \
  -e 'FREEE_CLIENT_ID=your_client_id_here' \
  -e 'FREEE_CLIENT_SECRET=your_client_secret_here' \
  -e 'TOKEN_STORAGE_PATH=/absolute/path/to/freee-mcp/tokens.enc' \
  -e 'FREEE_DEFAULT_COMPANY_ID=123456' \
  -e 'FREEE_TOKEN_ENCRYPTION_KEY=replace-with-strong-random-value' \
  -- node /absolute/path/to/freee-mcp/dist/index.js

VS Code (.vscode/mcp.json)

{
  "servers": {
    "freee": {
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "env": {
        "FREEE_CLIENT_ID": "your_client_id_here",
        "FREEE_CLIENT_SECRET": "your_client_secret_here",
        "TOKEN_STORAGE_PATH": "${workspaceFolder}/tokens.enc",
        "FREEE_DEFAULT_COMPANY_ID": "123456",
        "FREEE_TOKEN_ENCRYPTION_KEY": "replace-with-strong-random-value"
      }
    }
  }
}

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "freee": {
      "command": "node",
      "args": ["/absolute/path/to/freee-mcp/dist/index.js"],
      "env": {
        "FREEE_CLIENT_ID": "your_client_id_here",
        "FREEE_CLIENT_SECRET": "your_client_secret_here",
        "FREEE_TOKEN_DATA_BASE64": "base64-encoded-json",
        "FREEE_DEFAULT_COMPANY_ID": "123456",
        "FREEE_TOKEN_ENCRYPTION_KEY": "replace-with-strong-random-value"
      }
    }
  }
}

用法

身份验证方法

方法1：使用安装脚本（推荐）

运行交互式安装脚本：

npm run setup-auth

此脚本将：

1. 从加载凭据 .env 文件（如果可用）
2. 检查中的现有令牌 tokens.enc
3. 在浏览器中打开授权URL
4. 等待您授权并获取代码
5. 立即将代码兑换成代币
6. 将令牌保存到 tokens.enc 或显示环境变量

运行此脚本后，使用基于文件的令牌配置，如上面的Claude Desktop或VS Code示例。

方法2：环境变量

如果您已经有令牌，请通过环境变量提供它们（例如 FREEE_TOKEN_DATA_BASE64 在上面的游标示例中）。

方法3：手动流动（不推荐）

1. 获取授权URL：

Use tool: freee_get_auth_url

1. 在浏览器中访问URL并授权应用程序
2. 从重定向中复制授权码
3. 将代码替换为访问令牌：

Use tool: freee_get_access_token with code: "your_auth_code"

注意：授权码过期很快，因此此方法经常失败。

处理多家公司

freee MCP支持多家公司。当您进行身份验证时，服务器会自动访问与您的freee帐户关联的所有公司。

设置默认公司

避免指定 companyId 对于每个API调用，您可以设置默认的公司ID：

{
  "env": {
    "FREEE_DEFAULT_COMPANY_ID": "123456"
  }
}

要查找您的公司ID，请使用 freee_get_companies 验证后的工具。

使用多家公司

如果不设置默认公司ID，则必须指定 companyId 对于每个API调用：

// With default company ID set:
Use tool: freee_get_deals

// Without default company ID:
Use tool: freee_get_deals with companyId: 123456

可用工具

认证

• freee_get_auth_url -获取OAuth授权URL
• freee_get_access_token -访问令牌的Exchange身份验证码
• freee_set_company_token -为公司手动设置令牌

公司运营

• freee_get_companies -列出可访问的公司
• freee_get_company -获取公司详细信息

交易（交易）操作

• freee_get_deals -列出交易记录
• freee_get_deal -获取交易详情
• freee_create_deal -创建新交易

主数据

• freee_get_account_items -列出帐户项目
• freee_get_partners -列出合作伙伴
• freee_create_partner -创建新合作伙伴
• freee_get_sections -列出章节
• freee_get_tags -列表标签

发票操作

• freee_get_invoices -列出发票
• freee_create_invoice -创建新发票

报告

• freee_get_trial_balance -获取试算表报告
• freee_get_profit_loss -获取损益表- 营业利润最佳！
• freee_get_balance_sheet -获取资产负债表

高效获取营业利润

使用 API损益(freee_get_profit_loss) 通过单个API调用获取包括营业利润在内的财务数据。

# Example: Get operating profit for fiscal year 2024
Use tool: freee_get_profit_loss
Parameters:
- fiscalYear: 2024
- startMonth: 4    # Start of fiscal year
- endMonth: 3      # End of fiscal year

此API返回预先聚合的信息，包括：

• 收入
• 销售成本
• 毛利
• 销售、总务和管理费用
• 营业利润 ← Here!
• 营业外收入/支出
• 普通利润
• 特别损益
• 净利润增长

用法示例

查看月度营业利润趋势

# Operating profit from April to June 2024
Use tool: freee_get_profit_loss
Parameters:
- fiscalYear: 2024
- startMonth: 4
- endMonth: 6

获取营业利润同比比较

# Current period (FY2024)
Use tool: freee_get_profit_loss
Parameters:
- fiscalYear: 2024
- startMonth: 4
- endMonth: 9

# Previous period (FY2023)
Use tool: freee_get_profit_loss
Parameters:
- fiscalYear: 2023
- startMonth: 4
- endMonth: 9

合作伙伴经营利润分析

Use tool: freee_get_profit_loss
Parameters:
- fiscalYear: 2024
- startMonth: 4
- endMonth: 12
- breakdownDisplayType: "partner"  # Breakdown by partner

性能比较

单个交易的总营业利润可能需要数千次API调用和大量客户端处理。这 freee_get_profit_loss 该工具在单个请求中返回预聚合的报告数据，这大大降低了速率限制的使用率。对于大多数报告流程，从报告API开始，只有在需要详细深入时才获取原始交易。

这 freee_kpi_dashboard 该工具是第一个结构化输出PoC：它为当前客户端保留现有的文本响应，并返回 structuredContent 与公司、期间和盈利能力/安全性/效率/流动性KPI部分一起用于UI和自动化使用。

提示：设置 FREEE_DEFAULT_COMPANY_ID 所以报告称工作没有通过 companyId 每次。

发展

建筑

npm run build

发展模式

npm run dev

代码检查

npm run lint

类型检查

npm run typecheck

许可证管理

服务器自动管理OAuth令牌：

• 令牌存储在由指定的文件中 TOKEN_STORAGE_PATH
• 令牌过期时会自动刷新
• 每家公司都可以拥有自己的代币

错误处理

服务器为以下对象提供详细的错误消息：

• 身份验证失败
• API费率限制
• 无效参数
• 网络错误

安全

令牌安全

• 静态加密：所有令牌在存储前都使用AES-256-GCM进行加密
• 文件权限：令牌文件是使用0600权限创建的（仅限所有者读/写）
• 安全存储路径：默认情况下使用特定于平台的安全目录
• 自动刷新：代币在到期前5分钟刷新，以防止出现竞争情况
• 一次性刷新令牌：通过正确的错误恢复正确处理freee刷新令牌

一般安全指南

• 永远不要承诺你的 .env 文件或令牌文件
• 切勿提交嵌入机密的客户端配置文件（例如 .vscode/mcp.json, ~/.cursor/mcp.json，或Claude桌面配置文件）
• 保护您的客户机密
• 在项目目录外使用绝对路径存储令牌
• 将令牌存储在平台特定的安全位置（例如。， ~/.config/freee-mcp/)
• 使用 FREEE_TOKEN_ENCRYPTION_KEY 用于自定义加密密钥

令牌存储选项

基于文件的存储（默认）

# Default locations:
# macOS: ~/Library/Application Support/freee-mcp/tokens.enc
# Windows: %APPDATA%/freee-mcp/tokens.enc
# Linux: ~/.config/freee-mcp/tokens.enc

# Custom location via environment:
export TOKEN_STORAGE_PATH=/custom/path/tokens.enc

• 跨会话持续
• 使用可配置密钥加密
• 自动权限管理
• 需要文件系统访问权限

环境变量存储

# Base64 encoded token data (recommended for restricted environments)
export FREEE_TOKEN_DATA_BASE64="base64-encoded-json"

# Individual token variables (legacy)
export FREEE_ACCESS_TOKEN="your-access-token"
export FREEE_REFRESH_TOKEN="your-refresh-token"
# FREEE_COMPANY_ID is required to associate the token with a specific company
export FREEE_COMPANY_ID="12345"

• 适用于无服务器和受限环境（例如Claude Desktop）
• 无文件系统依赖关系
• 易于在CI/CD中管理

使用Gitleaks进行秘密检测

此项目使用 Gitleaks 为防止敏感数据意外泄露：

• 预提交钩子：每次提交前自动扫描机密
• CI/CD集成：GitHub Actions对所有PR运行安全扫描
• 自定义规则：检测特定于freee的凭据（客户端ID、密码、令牌）
• 手动扫描：运行 npm run gitleaks 在本地检查机密

可用命令：

npm run gitleaks        # Scan for secrets (non-blocking)
npm run gitleaks:ci     # Scan for secrets (CI mode, blocks on findings)

故障排除

身份验证问题

• 身份验证错误：确保您的客户ID和密码正确。重新运行 npm run setup-auth 如有需要
• “令牌刷新失败：invalid_grant”：freee刷新令牌是一次性使用的。通过运行重新进行身份验证 npm run setup-auth
• “未找到经过身份验证的公司”：运行 freee_get_auth_url 启动OAuth流，然后在浏览器中完成授权
• 令牌文件上的“权限被拒绝”：服务器自动修复权限。确保父目录可写
• “找不到令牌.enc”：在配置中使用绝对路径，或在受限环境中尝试环境变量存储

一般问题

• 令牌过期：服务器在到期前5分钟自动刷新令牌
• 费率限制：freee API有速率限制（3600个请求/小时）。使用聚合报告API来最大限度地减少调用
• 需要公司ID：大多数操作都需要公司ID。设置 FREEE_DEFAULT_COMPANY_ID 避免每次都指定它

许可证

麻省理工学院

支持

关于以下问题：

• 此MCP服务器：在此存储库中创建问题
• 免费API：咨询 freee开发者社区
• MCP协议：见 MCP文件