Content
freee-mcp
freee-mcp is an official MCP server and Agent Skills provided by freee that enables AI Agents to operate freee accounting, personnel, invoicing, time management, sales, and sign (electronic contract) features.
- MCP Server: Handles freee API calls, authentication, and request verification
- Agent Skills: Injects API references and operation recipes into the AI Agent's context to guide accurate API usage
[](https://www.npmjs.com/package/freee-mcp)
## Features
- Multi-API support: Supports 5 freee APIs: accounting, personnel, invoicing, time management, and sales
- Sign (electronic contract) support: Supports freee sign document management API with a dedicated command (`freee-sign-mcp`)
- OAuth 2.0 + PKCE: Secure authentication flow, automatic token update
- Multi-company support: Dynamic switching of companies is possible
## Agent Skills and MCP Communication Flow
Agent Skills (API reference and operation recipe) and MCP server (API call) are used in combination.
```mermaid
sequenceDiagram
participant User as User
participant Agent as AI Agent
participant Skill as Agent Skills<br/>(API Reference and Operation Recipe)
participant MCP as MCP Server
participant API as freee API
User->>Agent: Request<br/>「Get transaction list」
Note over Agent,Skill: 1. Agent Skills gets reference
Agent->>Skill: freee-api-skill call
Skill-->>Agent: API reference injection<br/>(endpoint, parameter specification)
Note over Agent,MCP: 2. MCP Tool executes API
Agent->>MCP: freee_api_get call<br/>path: /api/1/deals
MCP->>MCP: Verification with OpenAPI schema
MCP->>MCP: Authentication token grant
Note over MCP,API: 3. Communication with freee API
MCP->>API: GET /api/1/deals<br/>Authorization: Bearer xxx
API-->>MCP: JSON response
MCP-->>Agent: Transaction data
Agent-->>User: Formatted result display
```
This mechanism enables:
- Agent Skills: Injects necessary API references and operation recipes into the context (context efficiency)
- MCP: Handles authentication, request verification, and API calls
## Quick Start
### Method 1: Connect with Remote MCP (Recommended)
Connect to the Remote MCP server provided by freee. No local setup is required, and you can start using it immediately.
For Claude and Claude Desktop, open "Customize" and "Add custom connector", and set the following:
- Name: `freee`
- URL: `https://mcp.freee.co.jp/mcp`
> ⚠️ Be careful not to enter a URL other than the official freee URL.
<img src="docs/images/claude-desktop-custom-connector.png" width="600" alt="Add custom connector on Claude Desktop">
For other AI tools, follow their respective guides to add the Remote MCP server.
### Method 2: Run MCP Server Locally
Register a freee application and run the MCP server locally.
#### 2-1. Register freee Application
Create a new app on the [freee app store](https://app.secure.freee.co.jp/developers):
- Callback URL: `http://127.0.0.1:54321/callback`
- Obtain Client ID and Client Secret
- Check necessary permissions
#### 2-2. Setup
```bash
npx freee-mcp configure
```
The interactive wizard will set up authentication information, OAuth authentication, and company selection.
#### 2-3. Add to Claude Desktop
Add the configuration output by `configure` to the Claude Desktop configuration file:
```json
{
"mcpServers": {
"freee": {
"command": "npx",
"args": ["freee-mcp"]
}
}
}
```
For Windows Store (Microsoft Store) version of Claude Desktop, the configuration file path is different. `freee-mcp configure` automatically detects the appropriate path.
## Install Agent Skills
For Claude and Claude Desktop, open "Customize" and "Skills", and download and upload the latest `freee-api-skill.zip` from the [Releases](https://github.com/freee/freee-mcp/releases) page.
<img src="docs/images/claude-desktop-skill-upload.png" width="600" alt="Upload skill on Claude Desktop">
For coding agents like Claude Code (Cursor, OpenCode, etc.), install with [skills](https://www.npmjs.com/package/skills):
```bash
npx skills add freee/freee-mcp
```
Global installation (`-g`) and specific skill installation (`-s`) are also possible.
You can also install from GitHub CLI (v2.90.0 or later) with the [`gh skill`](https://cli.github.com/manual/gh_skill) command:
```bash
gh skill install freee/freee-mcp freee-api-skill
```
Supports specification of `--agent` (e.g., `claude-code`, `copilot`, `cursor`, `codex`, `gemini-cli`), `--scope user`/`--scope project`, and fixation to a specific tag/commit with `--pin`.
If you are using Agent Package Manager (APM), you can install with the following command:
```bash
apm install freee/freee-mcp/skills/freee-api-skill
```
## Use as Claude Code Plugin
When installed as a plugin on Claude Code, you can use the MCP server and Agent Skills (API reference and operation recipe) together.
Run the following two commands:
```bash
claude plugin marketplace add freee/freee-mcp
claude plugin install freee-mcp@freee-mcp-marketplace
```
You can also run these commands from within the Claude Code prompt:
```
/plugin marketplace add freee/freee-mcp
/plugin install freee-mcp@freee-mcp-marketplace
```
## Agent Skills Content
| API | Content | Number of Files |
| -------- | ------------------------------------------------ | -------------- |
| Accounting| Transactions, accounts, customers, invoices, expense claims, etc. | 32 |
| Personnel | Employees, attendance, salary slips, year-end adjustments, etc. | 28 |
| Invoicing| Invoices, estimates, delivery notes | 4 |
| Time Management | Projects, teams, partners, time, users, etc. | 7 |
| Sales | Cases, orders, masters | 5 |
| Sign | Documents, folders, templates, my seal, etc. | 8 |
When you request freee API operations during conversations with AI Agents, these references and recipes are referred to and executed accurately.
## Best Practices for Data Creation
When creating data with the same format repeatedly, such as invoices and expense claims, you can efficiently work by referring to previously created data:
- Invoice creation: Get past invoices and refer to customers, items, tax categories, etc.
- Expense claims: Refer to past claims and accurately specify accounts and departments
- Transaction registration: Refer to similar transactions and prevent input errors
```
Example: "Create this month's invoice based on last month's ○○ company invoice"
```
## Available Tools
### Management Tools
| Tool | Description | Notes |
| -------------------------- | ------------------ | ---------------- |
| `freee_authenticate` | Execute OAuth authentication | stdio only |
| `freee_auth_status` | Check authentication status | |
| `freee_clear_auth` | Clear authentication information | |
| `freee_set_current_company`| Switch companies | |
| `freee_get_current_company`| Display current company | |
| `freee_list_companies` | Get company list | |
| `freee_current_user` | Get current user information | |
| `freee_server_info` | Get server information | |
| `freee_file_upload` | File upload | stdio only |
### API Tools
Simple tool configuration for each HTTP method:
| Tool | Description | Example |
| ---------------------- | ------------------ | ---------------------- |
| `freee_api_get` | Data retrieval | `/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` | Get endpoint list | - |
Paths are automatically validated against the OpenAPI schema.
## freee Sign (Electronic Contract)
The freee sign API is available with the dedicated command `freee-sign-mcp`.
> Currently, it is only supported with local MCP server startup. Remote MCP support is in preparation.
### Setup
```bash
npx --package=freee-mcp -- freee-sign-mcp configure
```
The interactive wizard will set up authentication information and OAuth authentication.
### MCP Configuration
```json
{
"mcpServers": {
"freee-sign-mcp": {
"command": "npx",
"args": ["--package=freee-mcp", "--", "freee-sign-mcp"]
}
}
}
```
### Sign Tools
| Tool | Description |
| --- | --- |
| `sign_authenticate` | Execute OAuth authentication |
| `sign_auth_status` | Check authentication status |
| `sign_clear_auth` | Clear authentication information |
| `sign_api_get` | Data retrieval |
| `sign_api_post` | Create new |
| `sign_api_put` | Update |
| `sign_api_patch` | Partial update |
| `sign_api_delete` | Delete |
### Handling company_id
When including `company_id` in requests (parameters or body), it must match the current company. Mismatch will result in an error.
- Confirm company: `freee_get_current_company`
- Switch company: `freee_set_current_company`
- APIs without `company_id` (e.g., `/api/1/companies`) can be executed as is
## Contribution
See [CONTRIBUTING.md](./CONTRIBUTING.md) for details
### 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>
<a href="https://github.com/trpfrog"><img src="https://github.com/trpfrog.png" width="40" height="40" alt="@trpfrog"></a>
<a href="https://github.com/hoshinotsuyoshi"><img src="https://github.com/hoshinotsuyoshi.png" width="40" height="40" alt="@hoshinotsuyoshi"></a>
<a href="https://github.com/JeongJaeSoon"><img src="https://github.com/JeongJaeSoon.png" width="40" height="40" alt="@JeongJaeSoon"></a>
<a href="https://github.com/norimura114"><img src="https://github.com/norimura114.png" width="40" height="40" alt="@norimura114"></a>
<a href="https://github.com/akiras-ssrd"><img src="https://github.com/akiras-ssrd.png" width="40" height="40" alt="@akiras-ssrd"></a>
<a href="https://github.com/inoue2002"><img src="https://github.com/inoue2002.png" width="40" height="40" alt="@inoue2002"></a>
<a href="https://github.com/jacknocode"><img src="https://github.com/jacknocode.png" width="40" height="40" alt="@jacknocode"></a>
<a href="https://github.com/tnj"><img src="https://github.com/tnj.png" width="40" height="40" alt="@tnj"></a>
<a href="https://github.com/jaxx2104"><img src="https://github.com/jaxx2104.png" width="40" height="40" alt="@jaxx2104"></a>
<a href="https://github.com/kbyk004"><img src="https://github.com/kbyk004.png" width="40" height="40" alt="@kbyk004"></a>
<a href="https://github.com/k4200"><img src="https://github.com/k4200.png" width="40" height="40" alt="@k4200"></a>
<a href="https://github.com/fukumayuta"><img src="https://github.com/fukumayuta.png" width="40" height="40" alt="@fukumayuta"></a>
<a href="https://github.com/kenchan"><img src="https://github.com/kenchan.png" width="40" height="40" alt="@kenchan"></a>
<a href="https://github.com/EijiSugiura"><img src="https://github.com/EijiSugiura.png" width="40" height="40" alt="@EijiSugiura"></a>
<a href="https://github.com/ryuuuuma"><img src="https://github.com/ryuuuuma.png" width="40" height="40" alt="@ryuuuuma"></a>
<a href="https://github.com/toyamagu-2021"><img src="https://github.com/toyamagu-2021.png" width="40" height="40" alt="@toyamagu-2021"></a>
<a href="https://github.com/YasuakiOmokawa"><img src="https://github.com/YasuakiOmokawa.png" width="40" height="40" alt="@YasuakiOmokawa"></a>
<a href="https://github.com/Ryosuke-Watanabe9"><img src="https://github.com/Ryosuke-Watanabe9.png" width="40" height="40" alt="@Ryosuke-Watanabe9"></a>
<a href="https://github.com/Kitamura777"><img src="https://github.com/Kitamura777.png" width="40" height="40" alt="@Kitamura777"></a>
<a href="https://github.com/yuyohi"><img src="https://github.com/yuyohi.png" width="40" height="40" alt="@yuyohi"></a>
<!-- CONTRIBUTORS-END -->
## For Developers
```bash
git clone https://github.com/freee/freee-mcp.git
cd freee-mcp
bun install
bun run dev # Development server (watch mode)
bun run build # Build
bun run typecheck # Type check
bun run lint # Lint
bun run test:run # Test
# Regenerate API references
bun run generate:references
```
### Tech Stack
TypeScript / Model Context Protocol SDK / OAuth 2.0 + PKCE / Zod / Bun
### Architecture Details
For project architecture, internal structure, and development guidelines, see [CLAUDE.md](./CLAUDE.md).
## License
[Apache-2.0](./LICENSE)
## Community
We use Discord server for Q&A and information exchange. Feel free to join.
- [Discord Server](https://discord.gg/9ddTPGyxPw)
## Related Links
- [Introduction article: Public API MCP Agent Skill with freee-mcp](https://zenn.dev/him0/articles/766798ca1315e0)
- [freee API Documentation](https://developer.freee.co.jp/docs)
- [Model Context Protocol](https://modelcontextprotocol.io)
