freee/freee-mcp

它是什么

freee‑mcp 是一个官方桥梁，让 AI 代理（Claude、Codex、Cursor 等）能够与 freee 商业软件平台对话。它由两部分组成：

MCP 服务器 – 一个微型 Node.js 服务，处理 OAuth 2.0 + PKCE 认证，根据 freee 的 OpenAPI 规范验证请求，并将调用转发到 freee REST API。
Agent Skills – 描述每个 freee 端点（参数、请求格式、示例）的 JSON/YAML“配方”集合。当代理收到像“给我看看上个月的发票”这样的用户请求时，它会提取相关技能，构建正确的 API 调用，并将其发送到 MCP 服务器。

简而言之，它将自然语言命令转换为经过认证的 freee API 调用，涵盖会计、人力资源、发票、项目时间跟踪、销售、IT 资产管理、电子合同等。

角色	为什么重要
业务分析师 / 财务团队	他们可以让 LLM 获取或创建交易、发票、工资数据，而无需编写代码。
构建 AI 增强型机器人的开发者	将 MCP 服务器插入 Claude Code、OpenAI Codex、Cursor 等，立即让机器人访问 freee 的 12 模块 API。
自动化工程师	使用 CLI 工具（`freee_api_get`、`freee_api_post` 等）编写批量操作脚本，同时受益于 OpenAPI 验证。
freee 合作伙伴和 ISV	无需重新实现 OAuth 或请求验证，即可在其产品中提供“与 freee 对话”功能。

设置 – 注册 freee 应用程序，运行 npx freee-mcp configure（或连接到托管的 Remote MCP）。向导存储客户端 ID、密钥，并选择默认公司。
代理请求技能 – LLM 调用 freee-api-skill 包，返回端点定义和简短的“配方”。
代理构建请求 – 使用配方，代理构建如 freee_api_get('/api/1/deals') 的调用。
MCP 服务器验证 – 根据 OpenAPI 架构检查请求，添加 OAuth 持有者令牌，并将其转发到 https://api.freee.co.jp。
返回响应 – MCP 服务器将 JSON 传回给代理，代理将其格式化为人类可读的答案。

所有认证自动处理，令牌在需要时刷新。

广泛的 API 覆盖 – 12 个 freee 模块，557 个不同的操作（包括电子合同 freee-sign 命令）。
安全的 OAuth 2.0 + PKCE – 密钥不以明文存储；服务器刷新令牌。
动态公司切换 – freee_set_current_company 让单个 MCP 实例跨多个业务地点工作。
OpenAPI 驱动的验证 – 每个请求都根据 freee 的官方架构检查，防止格式错误的调用。
远程或本地 MCP – 使用托管服务器（https://mcp.freee.co.jp/mcp）即可立即启动，或自行运行 Node 服务器以完全控制。
现成的 Agent Skills – ZIP 文件（freee-api-skill.zip）包含完整参考集；可通过 Claude、skills、GitHub CLI 或 Microsoft APM 安装。
CLI 工具箱 – 用于手动测试或脚本化的简单命令（freee_api_get、freee_api_post、freee_file_upload 等）。
freee Sign 支持 – 专用于电子合同管理的 freee-sign-mcp 命令集（目前仅限本地）。

选择连接模式
- 远程：在 Claude Desktop → 自定义连接器 → 名称 freee，URL https://mcp.freee.co.jp/mcp。
- 本地：在 freee 开发者门户注册应用，然后运行 npx freee-mcp configure。
添加技能
- 从最新版本下载 freee-api-skill.zip 并上传到 Claude Desktop 的 Skills 界面，或运行 npx skills add freee/freee-mcp。
测试命令
```
npx freee_api_get /api/1/deals
```
CLI 将进行认证，调用 API，并打印 JSON 响应。
在 LLM 中使用
- 在 Claude 中，询问：“为 Acme Corp 创建一张新发票，15 万日元，下周五到期。”代理将获取适当的技能，调用 freee_api_post /api/1/invoices，并确认创建。

由 freee Inc. 维护 – 官方开源项目（Apache-2.0）。仓库列出了 30 多位贡献者。
开发工作流程 – bun 是包管理器；典型命令如 bun run dev、bun run build、bun run test:run 等。
扩展 – 添加新技能，使用 bun run generate:references 更新 OpenAPI 参考，或通过拉取请求贡献错误修复。详见 CONTRIBUTING.md。

freee-mcp = MCP 服务器 + 技能包，让 AI 代理通过自然语言提示安全地调用 freee 的商业软件 API（会计、人力资源、发票、合同等）。安装远程服务器或在本地运行，将技能包添加到您的 LLM，并通过对话式界面开始自动化 freee 任务。