Content
# freee-mcp
freee's official MCP server and Agent Skills that enable AI Agents to operate freee Accounting, Personnel, Invoicing, Work hour management, Sales, IT management, and Sign (electronic contract).
- 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
- Multiple API support: Supports 6 freee APIs: Accounting, Personnel, Invoicing, Work hour management, Sales, and IT management
- 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
- Multiple company support: Dynamic company switching
## 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 deal list"
Note over Agent,Skill: 1. Agent Skills retrieves 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 to freee API
MCP->>API: GET /api/1/deals<br/>Authorization: Bearer xxx
API-->>MCP: JSON response
MCP-->>Agent: Deal 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 freee's Remote MCP server. No local setup required.
For Claude and Claude Desktop, open "Customize" > "Add custom connector" and set:
- Name: `freee`
- URL: `https://mcp.freee.co.jp/mcp`
> ⚠️ Be cautious 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 in 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 configures authentication information, OAuth authentication, and company selection.
#### 2-3. Add to Claude Desktop
Add the configuration output by `configure` to Claude Desktop's configuration file:
```json
{
"mcpServers": {
"freee": {
"command": "npx",
"args": ["freee-mcp"]
}
}
}
```
For Windows Store (Microsoft Store) version of Claude Desktop, the configuration file path differs. `freee-mcp configure` automatically detects the appropriate path.
## Install Agent Skills
For Claude and Claude Desktop, open "Customize" > "Skills" and upload the latest `freee-api-skill.zip`.
- [Download the latest version (freee-api-skill.zip)](https://github.com/freee/freee-mcp/releases/latest/download/freee-api-skill.zip)
- Version history: [Releases page](https://github.com/freee/freee-mcp/releases)
<img src="docs/images/claude-desktop-skill-upload.png" width="600" alt="Upload skill in Claude Desktop">
For coding agents (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.
GitHub CLI (v2.90.0 and later) [`gh skill`](https://cli.github.com/manual/gh_skill) command:
```bash
gh skill install freee/freee-mcp freee-api-skill
```
Supports `--agent` (e.g., `claude-code`, `copilot`, `cursor`, `codex`, `gemini-cli`), `--scope user`/`--scope project`, and `--pin` for specific tags/commits.
[Agent Package Manager (APM)](https://github.com/microsoft/apm) usage:
```bash
apm install freee/freee-mcp/skills/freee-api-skill
```
## Use as Claude Code Plugin
Install as a plugin in Claude Code to use 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
```
Can also be executed from Claude Code prompt:
```
/plugin marketplace add freee/freee-mcp
/plugin install freee-mcp@freee-mcp-marketplace
```
## Use as Codex Plugin
Supports OpenAI Codex plugin marketplace. Use MCP server and Agent Skills (API reference and operation recipe) together.
Add marketplace with Codex CLI:
```bash
codex plugin marketplace add freee/freee-mcp
```
Launch Codex and open plugin list with `/plugins` slash command. Select `freee-mcp` and execute `Install plugin`.
Plugin definition in `.codex-plugin/plugin.json`, marketplace catalog in `.agents/plugins/marketplace.json`.
## Agent Skills Content
| API | Content | File count |
| -------- | ------------------------------------------------ | ---------- |
| Accounting| Transactions, accounts, customers, invoices, expense claims, etc. | 32 |
| Personnel| Employees, attendance, salary slips, year-end adjustments, etc. | 28 |
| Invoicing| Invoices, estimates, delivery notes | 6 |
| Work hour management| Projects, teams, partners, work hours, users, etc. | 7 |
| Sales | Cases, orders, masters | 10 |
| IT management| Members, SaaS accounts, equipment | 4 |
| Sign | Documents, folders, templates, stamps, etc. | 8 |
When requested to perform freee API operations during conversation with AI Agent, refer to these references and recipes for accurate execution.
## Best Practices for Data Creation
For repetitive data creation (invoices, expense claims, etc.), reference previously created data for efficient work:
- Invoice creation: Get past invoices, reference customers, items, tax categories, etc.
- Expense claim: Reference past claims, accurately specify accounts, departments, etc.
- Transaction registration: Reference similar transactions, prevent input errors
```
Example: "Create this month's invoice for XYZ Corporation based on last month's invoice"
```
## Available Tools
### Management Tools
| Tool | Description | Note |
| -------------------------- | ------------------ | ---------------- |
| `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` | Endpoint list | - |
Paths are automatically verified against OpenAPI schema.
## freee Sign (Electronic Contract)
freee Sign API available with dedicated command `freee-sign-mcp`.
> Remote MCP support is currently in preparation. Only local MCP server startup is supported.
### Setup
```bash
npx --package=freee-mcp -- freee-sign-mcp configure
```
Interactive wizard configures 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
Include `company_id` in requests (parameters or body) must match the current company. Mismatch results in an error.
- Confirm company: `freee_get_current_company`
- Switch company: `freee_set_current_company`
- APIs without `company_id` (e.g., `/api/1/companies`): Executable 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>
<a href="https://github.com/sakura20260508"><img src="https://github.com/sakura20260508.png" width="40" height="40" alt="@sakura20260508"></a>
<a href="https://github.com/bxg06523-cell"><img src="https://github.com/bxg06523-cell.png" width="40" height="40" alt="@bxg06523-cell"></a>
<a href="https://github.com/ryoya1122"><img src="https://github.com/ryoya1122.png" width="40" height="40" alt="@ryoya1122"></a>
<a href="https://github.com/Kanahiro"><img src="https://github.com/Kanahiro.png" width="40" height="40" alt="@Kanahiro"></a>
<a href="https://github.com/kagemeka"><img src="https://github.com/kagemeka.png" width="40" height="40" alt="@kagemeka"></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 checking
bun run lint # Lint
bun run test:run # Test
# Regenerate API references
bun run generate:references
```
### Technology 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
For questions and discussions, join our Discord server.
- [Discord Server](https://discord.gg/9ddTPGyxPw)
## Related Links
- [Introduction article: Public API as MCP with freee-mcp](https://zenn.dev/him0/articles/766798ca1315e0)
- [freee API Documentation](https://developer.freee.co.jp/docs)
- [Model Context Protocol](https://modelcontextprotocol.io)
