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

![CI](https://github.com/knishioka/freee-mcp/actions/workflows/ci.yml) ![codecov](https://codecov.io/gh/knishioka/freee-mcp) ![License: MIT](https://opensource.org/licenses/MIT)

模型上下文协议（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客户端配置。

我应该使用哪种方法？

用例	推荐方法
快速评估/无需Node.js开发设置	npx
主动开发/离线使用	本地构建

安装

克隆存储库：

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

安装依赖项：

npm install

构建TypeScript代码：

npm run build

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

cp .env.example .env

编辑 .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凭据

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

MCP客户端配置

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

环境变量

变量	必填	描述	默认值
`FREEE_CLIENT_ID`	是	freee OAuth应用程序客户端ID。如果缺少此ID，服务器将在启动时退出。	—
`FREEE_CLIENT_SECRET`	是	免费OAuth应用程序客户端密钥。如果缺少此项，服务器将在启动时退出。	—
`FREEE_DEFAULT_COMPANY_ID`	否	省略工具调用时使用的默认公司ID `companyId`.	—
`TOKEN_STORAGE_PATH`	否	加密令牌存储文件路径。	平台特定(`TokenManager.getDefaultStoragePath()`)
`FREEE_TOKEN_ENCRYPTION_KEY`	Yes	Secret用于导出用于令牌加密的AES-256-GCM密钥。如果缺少此项，服务器将在启动时退出。生成方式： `node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"`	—
`FREEE_TOKEN_DATA_BASE64`	否	Base64编码的JSON `[companyId, tokenData]` 启动时加载的元组。	—

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

此脚本将：

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

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

方法2：环境变量

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

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

获取授权URL：

Use tool: freee_get_auth_url

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

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文件

Freee MCP

快速接入

详细介绍