freee/freee-mcp

What it is

freee‑mcp is an official bridge that lets AI agents (Claude, Codex, Cursor, etc.) talk to the freee business‑software platform. It consists of two parts:

MCP server – a tiny Node.js service that handles OAuth 2.0 + PKCE authentication, validates requests against freee’s OpenAPI spec, and forwards calls to the freee REST APIs.
Agent Skills – a collection of JSON/YAML “recipes” that describe each freee endpoint (parameters, request shape, examples). When an agent receives a user request like “show me last month’s invoices” it pulls the relevant skill, builds the correct API call, and sends it to the MCP server.

In short, it turns natural‑language commands into authenticated freee API calls, covering accounting, HR, invoicing, project‑time tracking, sales, IT asset management, electronic contracts, and more.

Who might use it

Role	Why it matters
Business analysts / finance teams	They can ask an LLM to fetch or create transactions, invoices, payroll data without writing code.
Developers building AI‑augmented bots	Plug the MCP server into Claude Code, OpenAI Codex, Cursor, etc., and instantly give the bot access to freee’s 12‑module API.
Automation engineers	Use the CLI tools (`freee_api_get`, `freee_api_post`, …) to script bulk operations while still benefiting from OpenAPI validation.
Freee partners & ISVs	Offer a “talk‑to‑freee” feature in their products without re‑implementing OAuth or request validation.

How it works (high‑level flow)

Setup – Register a freee application, run npx freee-mcp configure (or connect to the hosted Remote MCP). The wizard stores client‑id, secret and picks a default company.
Agent asks for a skill – The LLM calls the freee‑api‑skill package, which returns the endpoint definition and a short “recipe”.
Agent builds a request – Using the recipe, the agent constructs a call like freee_api_get('/api/1/deals').
MCP server validates – It checks the request against the OpenAPI schema, adds the OAuth bearer token, and forwards it to https://api.freee.co.jp.
Response returns – The MCP server passes the JSON back to the agent, which formats a human‑readable answer.

All authentication is handled automatically; tokens are refreshed as needed.

Key features

Broad API coverage – 12 freee modules, 557 distinct operations (including electronic‑contract freee‑sign commands).
Secure OAuth 2.0 + PKCE – No secret is stored in plain text; the server refreshes tokens.
Dynamic company switching – freee_set_current_company lets a single MCP instance work across multiple business locations.
OpenAPI‑driven validation – Every request is checked against freee’s official schema, preventing malformed calls.
Remote or local MCP – Use the hosted server (https://mcp.freee.co.jp/mcp) for instant start‑up, or run the Node server yourself for full control.
Ready‑made Agent Skills – Zip file (freee-api-skill.zip) contains the full reference set; installable via Claude, skills, GitHub CLI, or Microsoft APM.
CLI toolbox – Simple commands (freee_api_get, freee_api_post, freee_file_upload, etc.) for manual testing or scripting.
Freee Sign support – Dedicated freee-sign-mcp command set for electronic contract management (local only for now).

Getting started (quick steps)

Choose connection mode
- Remote: In Claude Desktop → Custom Connector → name freee, URL https://mcp.freee.co.jp/mcp.
- Local: Register an app in the freee developer portal, then run npx freee-mcp configure.
Add the skill
- Download freee-api-skill.zip from the latest release and upload it in Claude Desktop’s Skills UI, or run npx skills add freee/freee-mcp.
Test a command
```
npx freee_api_get /api/1/deals
```
The CLI will authenticate, call the API, and print the JSON response.
Use in an LLM
- In Claude, ask: “Create a new invoice for Acme Corp, ¥150,000, due next Friday.” The agent will fetch the appropriate skill, call freee_api_post /api/1/invoices, and confirm the creation.

Who built it & how to contribute

Maintained by freee Inc. – an official open‑source project (Apache‑2.0). The repo lists over 30 contributors.
Development workflow – bun is the package manager; typical commands are bun run dev, bun run build, bun run test:run, etc.
Extending – Add new skills, update the OpenAPI reference with bun run generate:references, or contribute bug fixes via pull requests. See CONTRIBUTING.md for details.

TL;DR

freee-mcp = MCP server + skill bundle that lets AI agents securely call freee’s business‑software APIs (accounting, HR, invoicing, contracts, etc.) via natural‑language prompts. Install the remote server or run it locally, add the skill package to your LLM, and start automating freee tasks with a conversational interface.