How to Connect freee MCP to an AI Agent
Auth setup
1. Register at app.secure.freee.co.jp/developers. 2. Create app, set redirect_uri. 3. Get company_id from GET /companies. 4. Most endpoints require company_id param. 5. Or just use: npx freee-mcp (handles OAuth automatically).
Key facts
| Base URL | https://api.freee.co.jp/api/1/ |
|---|
| API version | v1 |
|---|
| Auth | OAuth 2.0 Authorization Code + PKCE. Register app at freee Developer Portal. Exchange auth code for access_token (expires 24h). Use refresh_token (expires 90 days) to renew. MCP server handles auth automatically via npx freee-mcp. |
|---|
| Token URL | https://accounts.secure.freee.co.jp/public_api/token |
|---|
| Scopes | read,write |
|---|
| Request body | application/json |
|---|
| Pagination | offset: use 'offset' and 'limit' params (max 100). Response includes total_count. |
|---|
| Rate limit | 3,600 requests/hour per access token. Wallets/deals endpoints: 300/5min. HTTP 429 with rate-limit headers. |
|---|
| Error format | JSON: {"status_code":400,"errors":[{"type":"validation","messages":["..."]}]} |
|---|
Key endpoints
| Method | Path | Description |
|---|
GET | /companies | List accessible companies (get company_id first) |
GET | /deals | List deals (invoices/transactions) |
POST | /deals | Create a new deal (invoice, expense, etc.) |
GET | /journals | List journal entries |
POST | /invoices | Create and send invoice |
GET | /account_items | List account items (勘定科目) |
Quickstart
GET /api/1/companies HTTP/1.1
Host: api.freee.co.jp
Authorization: Bearer {access_token}
Accept: application/json
Response: {"companies":[{"id":123,"display_name":"テスト株式会社","role":"admin"}]}
Agent pitfalls & tips
- Almost every endpoint requires company_id — always call GET /companies first to get it.
- Amount fields are integers in JPY (no decimal). 1000 = ¥1,000.
- Date format: YYYY-MM-DD. All dates are JST (UTC+9).
- The MCP server covers 5 domains: accounting, HR, payroll, expenses, invoicing. Use npx freee-mcp for the easiest setup.
- For tax filing (確定申告), use the /taxes endpoint group. Fiscal year closing requires specific workflow.
- Deal types: income (収入), expense (支出), transfer (振替). Use 'type' field.
Source: curated by KanseiLink from official documentation (docs) and registry checks. Last reviewed: 2026-07-06. Specs change — verify against the official docs before production use.
Frequently Asked Questions
What is freee MCP's AEO score?
▼
freee MCP has an AEO score of 1.00 and is rated AAA (Best-in-class agent integration). AEO (Agent Engine Optimization) measures how well a SaaS service works with AI agents. Scores range from 0.00 to 1.00, with grades from AAA (best) to D (not agent-ready).
Is freee MCP AI-agent-ready?
▼
freee MCP is currently ✓ verified for AI agent use. It offers an official MCP (Model Context Protocol) server, which means AI agents can connect directly. For detailed connection guides, auth setup, and known pitfalls, use the KanseiLink MCP tool.
How does freee MCP compare to other Accounting & Finance services?
▼
In the Accounting & Finance category, freee MCP is rated AAA. KanseiLink evaluates services based on MCP availability, API quality, documentation, auth-guide clarity, and integration recipe availability (methodology published). Visit the full rankings at kansei-link.com to see how freee MCP compares.
How can I integrate freee MCP with an AI agent?
▼
The fastest way to integrate freee MCP with an AI agent is through KanseiLink MCP. Install it with: npx @kansei-link/mcp-server — then use the search_services and get_service_detail tools to get the current auth setup, endpoints, rate limits, and agent-specific tips. This data is kept fresh from registry checks, curated official-doc guides, and agent reports.
How do I authenticate with freee MCP?
▼
OAuth 2.0 Authorization Code + PKCE. Register app at freee Developer Portal. Exchange auth code for access_token (expires 24h). Use refresh_token (expires 90 days) to renew. MCP server handles auth automatically via npx freee-mcp. Setup: 1. Register at app.secure.freee.co.jp/developers. 2. Create app, set redirect_uri. 3. Get company_id from GET /companies. 4. Most endpoints require company_id param. 5. Or just use: npx freee-mcp (handles OAuth automatically).
What are freee MCP's API rate limits?
▼
3,600 requests/hour per access token. Wallets/deals endpoints: 300/5min. HTTP 429 with rate-limit headers.