freee/freee-mcp

freee‑mcp – AI‑ready connector for the freee business‑software suite

What it is

• An official MCP (Model‑Context‑Protocol) server and a set of Agent Skills that let large‑language‑model agents (Claude, Codex, Cursor, etc.) call freee’s cloud APIs as if they were native commands.
• The MCP server handles OAuth 2.0 + PKCE authentication, token refresh, request validation against the freee OpenAPI schema, and routing to the appropriate freee endpoint.
• The Agent Skills package injects API reference data and ready‑made “recipes” (prompt snippets) into the LLM’s context so the model knows the exact endpoint, parameters and payload format for each operation.

Why it matters

• freee provides a comprehensive SaaS platform for accounting, HR, invoicing, project‑time tracking, sales, IT asset management, contract signing, etc. 10 distinct API groups are covered.
• By exposing these APIs through MCP, developers can build conversational assistants that “show me last month’s invoices” or “create a new expense claim” without writing any HTTP code themselves.
• The separation of Skills (knowledge) and MCP (execution) keeps the LLM prompt size small while guaranteeing that every call is validated against the official schema.

Key capabilities

Feature	What you get
Multi‑API support	Accounting, HR, invoicing, time‑tracking, sales, IT‑asset, fixed‑asset, contractor‑management, surveys, tax filing, and freee‑Sign electronic contracts (33 + 28 + … files).
Secure auth	OAuth 2.0 with PKCE, automatic token refresh, per‑company scoping.
Dynamic company switching	Change the active freee company on‑the‑fly; the server injects the correct company_id.
Request validation	Every call is checked against the OpenAPI spec before being sent to freee.
Remote or local MCP	Use freee’s hosted MCP endpoint (https://mcp.freee.co.jp/mcp) or run the server yourself after registering an app.
CLI tools	Small helper commands (freee_api_get, freee_api_post, freee_authenticate, etc.) for debugging and scripting.
Plugin integration	One‑click installation as a Claude Code, Claude Desktop, OpenAI Codex, or other LLM plugin via marketplace commands.
Package manager support	Install the skill with npx skills add freee/freee-mcp, GitHub CLI gh skill, or Microsoft APM.

Typical workflow

1. User asks an LLM‑powered assistant: “Give me a list of all deals for this month.”
2. The assistant calls the freee‑api‑skill to fetch the endpoint definition (GET /api/1/deals).
3. It invokes the local/remote MCP (freee_api_get /api/1/deals).
4. MCP validates the request, adds the OAuth bearer token, forwards it to the freee API, and returns the JSON response.
5. The assistant formats the data and replies to the user.

Getting started

• Remote MCP (recommended) – In Claude Desktop or any LLM UI, add a custom connector named freee pointing to https://mcp.freee.co.jp/mcp. No local setup needed.
• Local MCP – Register a freee app (callback http://127.0.0.1:54321/callback), run npx freee-mcp configure to store client‑id/secret and pick a company, then add the generated command block to your LLM’s connector config.
• Install the Skills – Download freee-api-skill.zip from the latest release and upload it in the LLM’s Skills UI, or run npx skills add freee/freee-mcp / gh skill install … for CLI‑based agents.
• Use the CLI – Commands like freee_api_get /api/1/deals or sign_api_post /api/1/sign_documents let you test the connection directly.

Use cases

• Finance assistants that retrieve balances, post journal entries, or generate tax‑filing reports on demand.
• HR bots that fetch employee lists, submit attendance records, or run payroll calculations.
• Invoice automation where a conversational UI creates, updates, or sends invoices by re‑using past documents.
• Contract signing workflows that upload a PDF to freee‑Sign, add signers, and poll for completion.
• Multi‑company dashboards that let a single LLM switch context between subsidiaries with freee_set_current_company.

Development & contribution

• Built with TypeScript, Bun, Zod for schema validation, and the Model‑Context‑Protocol SDK.
• Run bun install && bun run dev for a hot‑reloading dev server, bun run build for a production bundle, and bun run test:run for the test suite.
• Contributions are welcomed; see CONTRIBUTING.md and the Discord community for support.

License – Apache‑2.0.

---

All details above are taken directly from the repository’s README; no additional features have been inferred.