freee-api-skill

freee API Skill

Overview

This skill allows AI to directly operate freee data for accounting, HR and labor management, invoices, time tracking, sales, IT management, fixed assets, outsourcing management, surveys, business startup, HR evaluations, and tax filing.

freee-mcp (MCP server) to integrate with the freee API.

Role of this skill:

• Provide detailed references for the freee API
• Provide a freee-mcp usage guide and API call examples

Setup

freee_* tool is available, no setup is required.

Only if any of the following applies, read SETUP.md and guide the user through the connection procedure.

• freee_* Not a single tool is available
• freee_auth_status returns unauthenticated and the steps in "Error Handling" do not resolve it
• The user is asking about connection methods or initial setup

The connection mode can be checked in the freee_server_info transport field (remote = Remote MCP、stdio = local).

Reference

API reference is references/ are included. Each reference contains information on parameters, request bodies, and responses.

Procedure for finding the desired API:

1. references/INDEX.md (list of file names and contents by service)
2. If you cannot identify it from the index, references/ search the files within by keyword

Reference notation:

• 名前* is required, unmarked is optional
• In the heading, ### リクエストボディ* indicates that the request body itself is required
• Parameters are query unless otherwise specified.(path) (header) is specified in the relevant location
• At the end of a parameter name, [] is part of the parameter name and must not be omitted when calling the API
• GET /xxx と同じ indicates that the content is identical to the corresponding endpoint in the same file
• Responses list only top-level items. Check nested structures by actually calling the API

The correspondence between each element of corporate tax form XML (XTX / XBRL) and the items on paper forms is in tax-return-references/ . The index and common specifications are in tax-return-references/index.md , and the file for each form is looked up from the form list in that index by sheet_code (for series of attached tables and breakdown statements, multiple forms are combined in one file).

Usage

MCP Tools

Authentication and office management:

• freee_authenticate - OAuth authentication (authentication is handled automatically in Remote MCP, so it is usually unnecessary)
• freee_auth_status - Check authentication status
• freee_clear_auth - Clear authentication information (for local mode)
• freee_current_user - Get logged-in user information
• freee_list_companies - List offices
• freee_set_current_company - Switch office
• freee_get_current_company - Get current office

Server information:

• freee_server_info - Server information retrieval (version, transport: remote/stdio)

File operations:

• freee_file_upload - Upload file to file box (POST /api/1/receipts) *local mode only

API calls:

• freee_api_get - GET request
• freee_api_post - POST request
• freee_api_put - PUT request
• freee_api_delete - DELETE request
• freee_api_patch - PATCH request
• freee_api_list_paths - List of available API paths

service parameter (required):

• accounting - freee Accounting (transactions, accounts, partners, etc.) Example: /api/1/deals
• hr - freee HR & Labor (employees, attendance, etc.) Example: /api/v1/employees
• invoice - freee Invoicing (invoices, quotes, delivery notes) Example: /invoices
• pm - freee Time Tracking (projects, man-hours, etc.) Example: /projects
• sm - freee Sales (quotes, orders, sales, etc.) Example: /businesses
• it_management - freee IT Management (SaaS accounts, equipment, members) Example: /hub/it_management/members
• fixed_asset_management - freee Fixed Assets (list, details, create, update, delete of fixed assets) Example: /hub/fixed_asset_management/fixed_assets
• partner_management - freee Outsourcing Management (corporate users and departments of outsourcing contractors) Example: /hub/partner_management/orderer/company_users
• survey - freee Survey (survey projects, survey rounds) * Limited to freee-mcp (remote version) Example: /hub/survey/base_surveys
• launch - freee Startup (reference and update of data for startup applications) * Limited to freee-mcp (remote version) Example: /hub/launch/kaigyo_application
• employee_evaluation - HR Evaluation (retrieval of HR evaluation results) * Limited to freee-mcp (remote version) Example: /hub/employee_evaluation/evaluation_results
• tax_return - freee Tax Filing (corporate tax filing and form reference) Example: /hub/tax_return/corporate

Basic workflow

If the connection mode is unknown, you can check with freee_server_info (if transport is remote then Remote MCP,stdio , it is local). For Remote MCP, authentication is handled automatically, so you can start from step 1. If you are unauthenticated in local mode, run freee_authenticate first.

1. Check the company: freee_get_current_company to get the current company ID (required the first time. Once obtained within a session, it can be reused thereafter)
   • Since API data is separated by company, selecting the wrong company may result in accessing unintended data
2. Check the recipe: recipes/ Read the relevant recipe in
   • Since it summarizes common operation patterns and caveats, it is more efficient and less error-prone than calling the API directly
3. Search the reference: as needed, references/INDEX.md look up the relevant file from
   • Check detailed parameters and response specifications not covered in the recipe
4. Call the API: freee_api_* Use the tool (for endpoints that require company_id, use the value obtained in step 1)

Note:

• company_id must match the currently configured company. If it does not match, an error will occur
• To change the company: first freee_set_current_company switch with, then execute the request

Recipes

For sample use cases and tips for common operations, see below:

• recipes/expense-application-operations.md - Expense application
• recipes/deal-operations.md - Transactions (income and expenses)
• recipes/manual-journal-operations.md - Journal entries
• recipes/payment-request-operations.md - Payment requests
• recipes/hr-employee-operations.md - HR & Labor (employees and payroll)
• recipes/hr-attendance-operations.md - Attendance (clock-in/out, time stamping, break registration)
• recipes/invoice-operations.md - Invoices, Quotes, and Delivery Notes
• recipes/receipt-operations.md - File Box (upload and manage evidence files)
• recipes/pm-operations.md - Workload Management (projects and actual workload)
• recipes/pm-workload-registration.md - Safe Registration of Workload (PM/HR linked workflow)
• recipes/sm-operations.md - Sales Management (deals and orders)
• recipes/partner-management-operations.md - Outsourcing Management (reference to partners, corporate users, departments, projects, and tasks)
• recipes/it-management-operations.md - IT Management (members, SaaS accounts, and equipment)
• recipes/survey-operations.md - Surveys (retrieval of survey plans and survey sessions)
• recipes/launch-operations.md - Company Establishment (reference and update of data for establishment application)
• recipes/fixed-asset-management-operations.md - Fixed Asset Management (safe updates, deletion decisions, and handover to the Web UI)
• recipes/corporate-tax-return-operations.md - Filings (reference to corporate tax filings and forms)
• recipes/report-operations.md - Trial Balance and General Ledger (retrieval of reports and checking of unapproved journal entries)
• recipes/freee-mcp-tag.md - Guide for applying the memo tag "freee-mcp"

freee Sign (e-signature)

freee Sign is provided as a separate MCP server (freee-sign-mcp). sign_api_get If a signing tool such as SIGN-GUIDE.md is available, refer to

Data Visualization

When visualizing freee data with graphs, tables, HTML, etc., read COLORS.md and use the color scheme specified there.

Error Handling

• Version Check: Read VERSION.md to check the skill version (if the file does not exist, you are using the development version), and check the server version withfreee_server_info . If the skill version is older than the server, the skill information may not support the latest server. Please update the skill to the latest version and try again.
• Authentication Error (Remote MCP): The MCP client (such as Claude Desktop) will automatically prompt re-authentication. If the issue persists, delete the custom connector once and add it again.
• Authentication Error (Local): Check with freee_auth_status → freee_clear_auth → freee_authenticate
• Company Error: freee_list_companies → freee_set_current_company
• Details: See troubleshooting/INDEX.md (divided by symptom into auth / company / expense-errors / support)

About Endpoints Exclusive to freee-mcp (Remote Version)

Some API endpoints are available only with freee-mcp (Remote Version) and cannot be used in local mode. The corresponding recipes/ references/ has a note saying "⚠ freee-mcp (Remote Version) exclusive".

Before calling the relevant endpoint, check the transport with freee_server_info , and if it isstdio(local mode), do not call it; instead, guide the user to switch to freee-mcp (Remote Version) (setup instructions).

About API Feature Restrictions

Problems caused by feature restrictions of the freee API itself cannot be resolved by freee-mcp. For details, refer to troubleshooting/support.md .