Content
# freee-mcp
freee API MCP Server & Claude Plugin to make freee API available from Claude.
It is assumed that the MCP server (API calling function) and skill (API reference) are used in combination.
[](https://www.npmjs.com/package/freee-mcp)
> Note: This project is under development and unexpected problems may occur. If you find any problems, please report them as [Issue](https://github.com/freee/freee-mcp/issues).
## Features
- MCP Server: Directly call freee API from Claude Desktop / Claude Code
- Claude Plugin: Provides skills with detailed API reference documentation
- Multiple API support: Supports 5 freee APIs: Accounting, HR, Invoice, Time Management, and Sales
- OAuth 2.0 + PKCE: Secure authentication flow, automatic token renewal
- Multiple Business Support: Dynamic switching of businesses is possible
## SKILL and MCP Communication Flow
In Claude Code, SKILL (API reference) and MCP server (API call) are used in combination.
```mermaid
sequenceDiagram
participant User as ユーザー
participant Claude as Claude Code
participant Skill as Agent Skill<br/>(API リファレンス)
participant MCP as MCP サーバー<br/>(ローカル)
participant API as freee API
User->>Claude: リクエスト<br/>「取引一覧を取得して」
Note over Claude,Skill: 1. SKILL からリファレンスを取得
Claude->>Skill: freee-api-skill 呼び出し
Skill-->>Claude: API リファレンス注入<br/>(エンドポイント、パラメータ仕様)
Note over Claude,MCP: 2. MCP Tool で API を実行
Claude->>MCP: freee_api_get 呼び出し<br/>path: /api/1/deals
MCP->>MCP: OpenAPI スキーマで検証
MCP->>MCP: 認証トークン付与
Note over MCP,API: 3. freee API への通信
MCP->>API: GET /api/1/deals<br/>Authorization: Bearer xxx
API-->>MCP: JSON レスポンス
MCP-->>Claude: 取引データ
Claude-->>User: 結果を整形して表示
```
With this mechanism:
- SKILL: Injects the necessary API references into the context in stages (context efficiency)
- MCP: Responsible for authentication, request verification, and API calls
## Quick Start
### 1. freee Application Registration
Create a new app at [freee App Store](https://app.secure.freee.co.jp/developers):
- Callback URL: `http://127.0.0.1:54321/callback`
- Get Client ID and Client Secret
- Check the required permissions
### 2. Setup
```bash
npx freee-mcp configure
```
The interactive wizard will configure credentials, OAuth authentication, and business selection.
### 3. Add to Claude Desktop
Add the settings output by `configure` to the Claude Desktop configuration file:
| OS | 設定ファイルパス |
| ------- | ----------------------------------------------------------------- |
| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
| Linux | `~/.config/Claude/claude_desktop_config.json` |
```json
{
"mcpServers": {
"freee": {
"command": "npx",
"args": ["freee-mcp"]
}
}
}
```
> ⚠️ About setting with environment variables
> Setting with environment variables (`FREEE_CLIENT_ID`, `FREEE_CLIENT_SECRET`, etc.) is not recommended.
> Please run `npx freee-mcp configure` instead to migrate to the configuration file.
> Environment variable settings will be removed in a future version.
## Use as Claude Plugin
When installed as a plugin in Claude Code, you can use skills with API references:
```bash
npx add-skill freee/freee-mcp
```
[add-skill](https://github.com/anthropics/add-skill) is a skill installer that supports multiple coding agents such as Claude Code, Cursor, and OpenCode. Global installation (`-g`) and installation of specific skills only (`-s`) are also possible.
### Included References
| API | 内容 | ファイル数 |
| -------- | -------------------------------------------- | ---------- |
| 会計 | 取引、勘定科目、取引先、請求書、経費申請など | 31 |
| 人事労務 | 従業員、勤怠、給与明細、年末調整など | 27 |
| 請求書 | 請求書、見積書、納品書 | 3 |
| 工数管理 | ユーザー情報 | 1 |
| 販売 | 案件、受注 | 2 |
If you ask how to use the API during a conversation with Claude, it will refer to these references to provide accurate information.
### Best Practices for Data Creation
If you repeatedly create data of the same format, such as invoices and expense reports, you can work more efficiently by referring to previously created data:
- Invoice creation: Get past invoices and refer to the customer, item, tax classification, etc.
- Expense settlement: Refer to past applications to accurately specify accounts and departments
- Transaction registration: Refer to similar transactions to prevent input errors
```
Example: "Create this month's invoice based on last month's invoice to ○○ company."
```
## Available Tools
### Management Tools
| ツール | 説明 |
| -------------------------- | ------------------ |
| `freee_authenticate` | Execute OAuth authentication |
| `freee_auth_status` | Check authentication status |
| `freee_clear_auth` | Clear authentication information |
| `freee_set_current_company`| Switch business |
| `freee_get_current_company`| Display current business |
| `freee_list_companies` | Get a list of businesses |
| `freee_current_user` | Current user information |
### API Tools
Simple tool configuration for each HTTP method:
| ツール | 説明 | 例 |
| ---------------------- | ------------------ | ------------------ |
| `freee_api_get` | Get data | `/api/1/deals` |
| `freee_api_post` | Create new | `/api/1/deals` |
| `freee_api_put` | Update | `/api/1/deals/123` |
| `freee_api_delete` | Delete | `/api/1/deals/123` |
| `freee_api_patch` | Partial update | `/api/1/deals/123` |
| `freee_api_list_paths` | List of endpoints | - |
Paths are automatically validated against the OpenAPI schema.
### Handling of company_id
If you include `company_id` in the request (parameter or body), it must match the current business. If they do not match, an error will occur.
- Check business: `freee_get_current_company`
- Switch business: `freee_set_company`
- APIs that do not include company_id (e.g. `/api/1/companies`) can be executed as is
## Contribution
Bug reports, feature requests, and feedback are welcome in Issues!
This repository uses an AI-powered development flow, and implementing based on issues ensures code consistency and quality.
Therefore, PRs from users not on the whitelist will be automatically closed, and an issue reflecting the proposed content will be created instead.
The maintainer will consider the implementation policy based on the issue and proceed with the response.
### Contributors
<!-- CONTRIBUTORS-START -->
<a href="https://github.com/him0"><img src="https://github.com/him0.png" width="40" height="40" alt="@him0"></a>
<a href="https://github.com/dais0n"><img src="https://github.com/dais0n.png" width="40" height="40" alt="@dais0n"></a>
<a href="https://github.com/HikaruEgashira"><img src="https://github.com/HikaruEgashira.png" width="40" height="40" alt="@HikaruEgashira"></a>
<a href="https://github.com/nakanoasaservice"><img src="https://github.com/nakanoasaservice.png" width="40" height="40" alt="@nakanoasaservice"></a>
<a href="https://github.com/tackeyy"><img src="https://github.com/tackeyy.png" width="40" height="40" alt="@tackeyy"></a>
<a href="https://github.com/worldscandy"><img src="https://github.com/worldscandy.png" width="40" height="40" alt="@worldscandy"></a>
<a href="https://github.com/akhr77"><img src="https://github.com/akhr77.png" width="40" height="40" alt="@akhr77"></a>
<!-- CONTRIBUTORS-END -->
## For developers
```bash
git clone https://github.com/freee/freee-mcp.git
cd freee-mcp
pnpm install
pnpm dev # Development server (watch mode)
pnpm build # Build
pnpm typecheck # Type check
pnpm lint # Lint
pnpm test:run # Test
# Regenerate API references
pnpm generate:references
```
### Technical Stack
TypeScript / Model Context Protocol SDK / OAuth 2.0 + PKCE / Zod / esbuild
### Architecture Details
See [CLAUDE.md](./CLAUDE.md) for project architecture, internal structure, and development guidelines.
## License
Apache-2.0
## Community
Questions and information exchange are conducted on the Discord server. Please feel free to join us.
- [Discord Server](https://discord.gg/9ddTPGyxPw)
## Related Links
- [Introduction article: When MCPizing a Public API, it seems good to use Agent Skill together with freee-mcp](https://zenn.dev/him0/articles/766798ca1315e0)
- [freee API Documentation](https://developer.freee.co.jp/docs)
- [Model Context Protocol](https://modelcontextprotocol.io)
