星战科技xingzhan.cloud
返回市场
自由-mcp

自由-mcp

作者：knishioka1 星标更新：2025-10-27
安装使用来源：spider==github.com

项目介绍

MCP Server for freee Accounting API

CI codecov License: MIT

这是一个提供与freee会计软件API集成的Model Context Protocol (MCP)服务器，使AI助手能够与会计数据进行交互。

功能

  • 支持OAuth 2.0认证流程
  • 公司管理
  • 交易（交易）操作
  • 账目项目管理
  • 合作伙伴管理
  • 部门和标签
  • 发票创建和管理
  • 试算平衡报告
  • 令牌持久化和自动刷新

前提条件

  • Node.js 20或更高版本
  • freee API凭证（客户端ID和客户端密钥）
  • 具有API访问权限的freee账户

安装

  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文件，填写您的freee 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.json

配置

获取freee API凭证

  1. 登录到您的freee账户
  2. 访问freee应用商店
  3. 创建一个新的应用程序
  4. 记下客户端ID和客户端密钥
  5. 设置重定向URI（本地开发时使用urn:ietf:wg:oauth:2.0:oob）

MCP客户端配置

Claude Desktop配置

  1. 确保服务器已构建（参见安装步骤3）

  2. 找到配置文件：

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

  3. 选择您的配置方法：

    选项A：使用tokens.json（推荐在运行setup-auth后使用）

    {
  "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.json",
        "FREEE_DEFAULT_COMPANY_ID": "123456"  // 可选：设置默认公司ID
      }
    }
  }
}

    选项B：使用环境变量存储令牌

    {
  "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_ACCESS_TOKEN": "your_access_token",
        "FREEE_REFRESH_TOKEN": "your_refresh_token",
        "FREEE_COMPANY_ID": "your_company_id"
      }
    }
  }
}

  4. 重启Claude Desktop以应用配置。

  5. 验证服务器是否运行，检查Claude中是否可用freee工具。尝试询问“有哪些可用的freee工具？”

其他MCP客户端

对于其他MCP客户端，根据需要调整配置格式：

使用

认证方法

方法1：使用设置脚本（推荐）

运行交互式设置脚本：

npm run setup-auth

此脚本会：

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

运行此脚本后，请使用上述Claude Desktop配置中的选项A。

方法2：环境变量

如果您已有令牌，可以直接将其设置在Claude Desktop配置中。使用上述Claude Desktop配置中的选项B，并填写实际的令牌值。

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

  1. 获取授权URL：
使用工具：freee_get_auth_url
  1. 在浏览器中访问该URL并授权应用程序
  2. 从重定向中复制授权码
  3. 使用授权码交换访问令牌：
使用工具：freee_get_access_token with code: "your_auth_code"

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

处理多个公司

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

设置默认公司

为了避免每次API调用都需要指定companyId，您可以设置一个默认公司ID：

{
  "env": {
    "FREEE_DEFAULT_COMPANY_ID": "123456"  // 您的默认公司ID
  }
}

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

使用多个公司

如果没有设置默认公司ID，则必须为每个API调用指定companyId：

// 已设置默认公司ID：
使用工具：freee_get_deals

// 未设置默认公司ID：
使用工具：freee_get_deals with companyId: 123456

可用工具

认证

  • freee_get_auth_url - 获取OAuth授权URL
  • freee_get_access_token - 交换授权码以获取访问令牌
  • 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 - 获取资产负债表
  • freee_get_cash_flow - 获取现金流量表

高效获取营业利润

避免检索大量单独的交易，而是使用损益API (freee_get_profit_loss)，通过一次API调用即可获取包括营业利润在内的财务数据。

# 示例：获取2024财年的营业利润
使用工具：freee_get_profit_loss
参数：
- fiscalYear: 2024
- startMonth: 4    # 财年起点
- endMonth: 3      # 财年终点

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

  • 收入
  • 销售成本
  • 毛利
  • 销售、一般及行政费用
  • 营业利润 ← 这里！
  • 非经营收入/支出
  • 经常性利润
  • 非经常性收益/损失
  • 净收入

使用示例

检查月度营业利润趋势

# 2024年4月至6月的营业利润
使用工具：freee_get_profit_loss
参数：
- fiscalYear: 2024
- startMonth: 4
- endMonth: 6

获取年度比较的营业利润

# 当前期间（FY2024）
使用工具：freee_get_profit_loss
参数：
- fiscalYear: 2024
- startMonth: 4
- endMonth: 9

# 上一期间（FY2023）
使用工具：freee_get_profit_loss  
参数：
- fiscalYear: 2023
- startMonth: 4
- endMonth: 9

按合作伙伴分析营业利润

使用工具：freee_get_profit_loss
参数：
- fiscalYear: 2024
- startMonth: 4
- endMonth: 12
- breakdownDisplayType: "partner"  # 按合作伙伴细分

性能对比

方法API调用数据处理对速率限制的影响
单个交易聚合数千到数万次需要在客户端侧进行聚合高风险（可能会达到限制）
损益API1次调用服务器侧预聚合极低风险

实际案例：年度营业利润检索

  • 传统方法：10,000笔交易 → 10,000次API调用 → 占用27%的速率限制
  • 高效方法：freee_get_profit_loss → 1次API调用 → 占用0.03%的速率限制

开发

构建

npm run build

开发模式

npm run dev

代码检查

npm run lint

类型检查

npm run typecheck

令牌管理

服务器自动管理OAuth令牌：

  • 令牌存储在由TOKEN_STORAGE_PATH指定的文件中
  • 令牌到期时会自动刷新
  • 每个公司可以有自己的令牌

错误处理

服务器提供详细的错误消息：

  • 认证失败
  • API速率限制
  • 参数无效
  • 网络错误

安全

快速安全指南

  • 不要提交您的.env文件或tokens.json
  • 保护好您的客户端密钥
  • 使用环境变量存储敏感数据
  • 令牌会自动刷新以维持安全性
  • 设置严格的文件权限（600）在令牌存储文件上
  • 使用绝对路径将令牌存储在项目目录外

使用Gitleaks检测秘密

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

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

可用命令：

npm run gitleaks        # 扫描秘密（非阻塞）
npm run gitleaks:ci     # 扫描秘密（CI模式，发现时阻塞）

全面的安全文档

有关详细的安全最佳实践、OAuth实现指南以及针对Claude Desktop的具体考虑，请参阅我们的MCP认证指南。

指南涵盖：

  • OAuth 2.1安全要求
  • 安全的令牌存储模式
  • Claude Desktop环境变量的解决方法
  • 常见的安全陷阱及其解决方案
  • 测试和CI/CD安全实践

故障排除

  1. 认证错误：确保您的客户端ID和密钥正确
  2. 令牌过期：服务器会自动刷新令牌
  3. 速率限制：freee API具有速率限制（每小时3,600次请求）
  4. 需要公司ID：大多数操作都需要公司ID

许可

MIT

支持

对于以下问题：