The freee-mcp server exposes the freee API through an MCP server that Claude Code can call locally. It combines an API-calling MCP backend with a contextual Skill reference so Claude can inject API contract details and validate requests before hitting the freee API. The setup supports OAuth 2.0 with PKCE for secure authentication and can handle multiple Freee domains (e.g., accounting, HR, invoicing, times, and sales) via OpenAPI-driven validation. Tools in this MCP include both management helpers (to authenticate, switch offices, and inspect current user) and API helpers (to perform REST operations and validate paths against the OpenAPI schema). You can interact with the server from Claude Code by invoking tools such as freee_api_get, freee_api_post, and freee_authenticate, which are wired to the OpenAPI schema and token handling behind the scenes.

To use it from Claude Code, first ensure your MCP server is running (as configured in your Claude Desktop settings). Then use the API tools to perform calls like listing deals or creating invoices. The Skill provides the API reference and parameter specs, which Claude Code injects into the conversation to guide correct requests. If you need to switch the current company (office) for subsequent requests, you can call the management tools to set the active office; the API tools will enforce company_id alignment where required. The integration aims to provide a smooth workflow where API references are contextualized in the chat and actual API calls are executed securely through the MCP backend.

Prerequisites:

• Node.js and npm (or a compatible Node.js environment)
• Git
• Optional: pnpm (recommended as shown in development steps)

Steps:

1. Clone the repository git clone https://github.com/freee/freee-mcp.git cd freee-mcp

2. Install dependencies (using pnpm as per the project guidance) pnpm install

3. Configure the MCP server (optional for local testing)

   • Ensure Node.js is available
   • If you plan to run in development mode, install dev dependencies and build as needed

4. Run the development server pnpm dev

   or build for production

   pnpm build

5. Generate API references (if you need to refresh the embedded API docs) pnpm generate:references

6. Add the MCP server to Claude Desktop configuration (as shown in the README example): { "mcpServers": { "freee": { "command": "npx", "args": ["freee-mcp"] } } }

Prerequisites recap: Node.js environment, Git access, and an installed package manager (pnpm recommended by the project). Follow the steps to install dependencies, run the dev server, and optionally generate updated API references.

Notes and tips:

• OAuth 2.0 + PKCE is used for secure authentication; you will configure credentials during the initial setup with npx freee-mcp configure.
• The MCP supports multiple Freee APIs (Accounting, HR/Payroll, Invoices, Time Tracking, and Sales). The OpenAPI schema is used to validate request paths and parameters.
• When including company_id in a request, ensure it matches the currently selected office; otherwise, the request will error.
• If you encounter token expiration, the MCP will refresh tokens automatically if configured with a refresh flow.
• Claude Code Plugin installation (claude plugin add freee/freee-mcp) bundles the MCP server with a Skill reference for a streamlined experience.
• If you only want the Skill reference without the MCP, you can install the Skill package directly via npm (npx skills add freee/freee-mcp).
• The README provides guidance for using the management tools (freee_authenticate, freee_auth_status, freee_clear_auth, freee_set_current_company, freee_get_current_company, freee_list_companies, freee_current_user) and API tools (freee_api_get, freee_api_post, freee_api_put, freee_api_delete, freee_api_patch, freee_api_list_paths).
• Ensure the Claude Desktop configuration paths match your OS when integrating the MCP server; the README includes a cross-platform example JSON snippet.