knishioka/freee-mcp

MCP Server for freee Accounting API

A Model Context Protocol (MCP) server that provides integration with freee accounting software API, enabling AI assistants to interact with accounting data.

Features

• OAuth 2.0 authentication flow support
• Company management
• Transaction (Deal) operations
• Account items management
• Partner management
• Sections and Tags
• Invoice creation and management
• Trial balance reports
• Token persistence and automatic refresh

Prerequisites

• Node.js 20 or higher
• freee API credentials (Client ID and Client Secret)
• freee account with API access

Quick Start

Choose one of the following methods to get started:

Option A: npx (no local build required)

Add the following to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "freee": {
      "command": "npx",
      "args": ["-y", "github:knishioka/freee-mcp"],
      "env": {
        "FREEE_CLIENT_ID": "your_client_id",
        "FREEE_CLIENT_SECRET": "your_client_secret",
        "FREEE_TOKEN_ENCRYPTION_KEY": "replace-with-strong-random-value"
      }
    }
  }
}

Note: The first launch with npx may take 30–60 seconds while dependencies are downloaded and TypeScript is compiled. Subsequent launches will be faster.

Option B: Local build

git clone https://github.com/knishioka/freee-mcp.git
cd freee-mcp
npm install && npm run build

{
  "mcpServers": {
    "freee": {
      "command": "node",
      "args": ["/absolute/path/to/freee-mcp/dist/index.js"],
      "env": {
        "FREEE_CLIENT_ID": "your_client_id",
        "FREEE_CLIENT_SECRET": "your_client_secret",
        "FREEE_TOKEN_ENCRYPTION_KEY": "replace-with-strong-random-value"
      }
    }
  }
}

See the Installation section for detailed setup instructions including environment variables and additional MCP client configurations.

Which method should I use?

Installation

1. Clone the repository:

git clone https://github.com/knishioka/freee-mcp.git
cd freee-mcp

2. Install dependencies:

npm install

3. Build the TypeScript code:

npm run build

4. Copy the environment example file and configure it:

cp .env.example .env

5. Edit .env with your freee API credentials:

FREEE_CLIENT_ID=your_client_id_here
FREEE_CLIENT_SECRET=your_client_secret_here
FREEE_REDIRECT_URI=urn:ietf:wg:oauth:2.0:oob
# TOKEN_STORAGE_PATH=./tokens.enc  # Optional: defaults to platform-specific secure path

Configuration

Getting freee API Credentials

1. Log in to your freee account
2. Go to the freee App Store
3. Create a new application
4. Note down the Client ID and Client Secret
5. Set the redirect URI (use urn:ietf:wg:oauth:2.0:oob for local development)

MCP Client Configuration

Build the server first (npm run build), then configure one of the clients below.

Environment Variables

{
  "mcpServers": {
    "freee": {
      "command": "node",
      "args": ["/absolute/path/to/freee-mcp/dist/index.js"],
      "env": {
        "FREEE_CLIENT_ID": "your_client_id_here",
        "FREEE_CLIENT_SECRET": "your_client_secret_here",
        "TOKEN_STORAGE_PATH": "/absolute/path/to/freee-mcp/tokens.enc",
        "FREEE_DEFAULT_COMPANY_ID": "123456",
        "FREEE_TOKEN_ENCRYPTION_KEY": "replace-with-strong-random-value"
      }
    }
  }
}

claude mcp add freee \
  -e 'FREEE_CLIENT_ID=your_client_id_here' \
  -e 'FREEE_CLIENT_SECRET=your_client_secret_here' \
  -e 'TOKEN_STORAGE_PATH=/absolute/path/to/freee-mcp/tokens.enc' \
  -e 'FREEE_DEFAULT_COMPANY_ID=123456' \
  -e 'FREEE_TOKEN_ENCRYPTION_KEY=replace-with-strong-random-value' \
  -- node /absolute/path/to/freee-mcp/dist/index.js

{
  "servers": {
    "freee": {
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "env": {
        "FREEE_CLIENT_ID": "your_client_id_here",
        "FREEE_CLIENT_SECRET": "your_client_secret_here",
        "TOKEN_STORAGE_PATH": "${workspaceFolder}/tokens.enc",
        "FREEE_DEFAULT_COMPANY_ID": "123456",
        "FREEE_TOKEN_ENCRYPTION_KEY": "replace-with-strong-random-value"
      }
    }
  }
}

{
  "mcpServers": {
    "freee": {
      "command": "node",
      "args": ["/absolute/path/to/freee-mcp/dist/index.js"],
      "env": {
        "FREEE_CLIENT_ID": "your_client_id_here",
        "FREEE_CLIENT_SECRET": "your_client_secret_here",
        "FREEE_TOKEN_DATA_BASE64": "base64-encoded-json",
        "FREEE_DEFAULT_COMPANY_ID": "123456",
        "FREEE_TOKEN_ENCRYPTION_KEY": "replace-with-strong-random-value"
      }
    }
  }
}

Usage

Authentication Methods

Method 1: Using Setup Script (Recommended)

Run the interactive setup script:

npm run setup-auth

This script will:

1. Load credentials from .env file if available
2. Check for existing tokens in tokens.enc
3. Open the authorization URL in your browser
4. Wait for you to authorize and get the code
5. Exchange the code for tokens immediately
6. Save tokens to tokens.enc or display environment variables

After running this script, use a file-based token configuration like the Claude Desktop or VS Code examples above.

Method 2: Environment Variables

If you already have tokens, provide them via environment variables (for example FREEE_TOKEN_DATA_BASE64 in the Cursor example above).

Method 3: Manual Flow (Not Recommended)

1. Get the authorization URL:

Use tool: freee_get_auth_url

2. Visit the URL in a browser and authorize the application
3. Copy the authorization code from the redirect
4. Exchange the code for an access token:

Use tool: freee_get_access_token with code: "your_auth_code"

Note: The authorization code expires quickly, so this method often fails.

Handling Multiple Companies

freee MCP supports multiple companies. When you authenticate, the server automatically obtains access to all companies associated with your freee account.

Setting a Default Company

To avoid specifying companyId for every API call, you can set a default company ID:

{
  "env": {
    "FREEE_DEFAULT_COMPANY_ID": "123456"
  }
}

To find your company IDs, use the freee_get_companies tool after authentication.

Using Multiple Companies

If you don't set a default company ID, you must specify companyId for each API call:

// With default company ID set:
Use tool: freee_get_deals

// Without default company ID:
Use tool: freee_get_deals with companyId: 123456

Available Tools

Authentication

• freee_get_auth_url - Get OAuth authorization URL
• freee_get_access_token - Exchange auth code for access token
• freee_set_company_token - Manually set token for a company

Company Operations

• freee_get_companies - List accessible companies
• freee_get_company - Get company details

Transaction (Deal) Operations

• freee_get_deals - List transactions
• freee_get_deal - Get transaction details
• freee_create_deal - Create new transaction

Master Data

• freee_get_account_items - List account items
• freee_get_partners - List partners
• freee_create_partner - Create new partner
• freee_get_sections - List sections
• freee_get_tags - List tags

Invoice Operations

• freee_get_invoices - List invoices
• freee_create_invoice - Create new invoice

Reports

• freee_get_trial_balance - Get trial balance report
• freee_get_profit_loss - Get profit and loss statement - Optimal for operating profit!
• freee_get_balance_sheet - Get balance sheet

Efficient Operating Profit Retrieval

Instead of retrieving large amounts of individual transactions, use the Profit & Loss API (freee_get_profit_loss) to get financial data including operating profit with a single API call.

# Example: Get operating profit for fiscal year 2024
Use tool: freee_get_profit_loss
Parameters:
- fiscalYear: 2024
- startMonth: 4    # Start of fiscal year
- endMonth: 3      # End of fiscal year

This API returns pre-aggregated information including:

• Revenue
• Cost of goods sold
• Gross profit
• Selling, general & administrative expenses
• Operating profit ← Here!
• Non-operating income/expenses
• Ordinary profit
• Extraordinary gains/losses
• Net income

Usage Examples

Check Monthly Operating Profit Trends

# Operating profit from April to June 2024
Use tool: freee_get_profit_loss
Parameters:
- fiscalYear: 2024
- startMonth: 4
- endMonth: 6

Get Operating Profit for Year-over-Year Comparison

# Current period (FY2024)
Use tool: freee_get_profit_loss
Parameters:
- fiscalYear: 2024
- startMonth: 4
- endMonth: 9

# Previous period (FY2023)
Use tool: freee_get_profit_loss
Parameters:
- fiscalYear: 2023
- startMonth: 4
- endMonth: 9

Partner-wise Operating Profit Analysis

Use tool: freee_get_profit_loss
Parameters:
- fiscalYear: 2024
- startMonth: 4
- endMonth: 12
- breakdownDisplayType: "partner"  # Breakdown by partner

Performance Comparison

Aggregating operating profit from individual deals can require thousands of API calls and significant client-side processing. The freee_get_profit_loss tool returns pre-aggregated report data in a single request, which dramatically reduces rate-limit usage. For most reporting flows, start with report APIs and only fetch raw deals when you need detailed drill-down.

Tip: Set FREEE_DEFAULT_COMPANY_ID so report calls work without passing companyId each time.

Development

Building

npm run build

Development Mode

npm run dev

Linting

npm run lint

Type Checking

npm run typecheck

Token Management

The server automatically manages OAuth tokens:

• Tokens are stored in the file specified by TOKEN_STORAGE_PATH
• Tokens are automatically refreshed when they expire
• Each company can have its own token

Error Handling

The server provides detailed error messages for:

• Authentication failures
• API rate limits
• Invalid parameters
• Network errors

Security

Token Security

• Encryption at Rest: All tokens are encrypted using AES-256-GCM before storage
• File Permissions: Token files are created with 0600 permissions (owner read/write only)
• Secure Storage Paths: Platform-specific secure directories are used by default
• Automatic Refresh: Tokens are refreshed 5 minutes before expiry to prevent race conditions
• Single-Use Refresh Tokens: freee refresh tokens are handled correctly with proper error recovery

General Security Guidelines

• Never commit your .env file or token files
• Never commit client config files that embed secrets (for example .vscode/mcp.json, ~/.cursor/mcp.json, or Claude Desktop config files)
• Keep your Client Secret secure
• Use absolute paths for token storage outside the project directory
• Store tokens in platform-specific secure locations (e.g., ~/.config/freee-mcp/)
• Use FREEE_TOKEN_ENCRYPTION_KEY for custom encryption keys

Token Storage Options

File-Based Storage (Default)

# Default locations:
# macOS: ~/Library/Application Support/freee-mcp/tokens.enc
# Windows: %APPDATA%/freee-mcp/tokens.enc
# Linux: ~/.config/freee-mcp/tokens.enc

# Custom location via environment:
export TOKEN_STORAGE_PATH=/custom/path/tokens.enc

• Persistent across sessions
• Encrypted with configurable key
• Automatic permission management
• Requires file system access

Environment Variable Storage

# Base64 encoded token data (recommended for restricted environments)
export FREEE_TOKEN_DATA_BASE64="base64-encoded-json"

# Individual token variables (legacy)
export FREEE_ACCESS_TOKEN="your-access-token"
export FREEE_REFRESH_TOKEN="your-refresh-token"
# FREEE_COMPANY_ID is required to associate the token with a specific company
export FREEE_COMPANY_ID="12345"

• Works in serverless and restricted environments (e.g., Claude Desktop)
• No file system dependencies
• Easy to manage in CI/CD

Secret Detection with Gitleaks

This project uses Gitleaks to prevent accidental exposure of sensitive data:

• Pre-commit Hook: Automatically scans for secrets before each commit
• CI/CD Integration: GitHub Actions runs security scans on all PRs
• Custom Rules: Detects freee-specific credentials (Client ID, Secret, tokens)
• Manual Scanning: Run npm run gitleaks to check for secrets locally

Available Commands:

npm run gitleaks        # Scan for secrets (non-blocking)
npm run gitleaks:ci     # Scan for secrets (CI mode, blocks on findings)

Troubleshooting

Authentication Issues

• Authentication errors: Ensure your Client ID and Secret are correct. Re-run npm run setup-auth if needed
• "Token refresh failed: invalid_grant": freee refresh tokens are single-use. Re-authenticate by running npm run setup-auth
• "No authenticated companies found": Run freee_get_auth_url to start OAuth flow, then complete authorization in browser
• "Permission denied" on token file: Server automatically fixes permissions. Ensure parent directory is writable
• "Cannot find tokens.enc": Use absolute paths in configuration, or try environment variable storage for restricted environments

General Issues

• Token expiration: The server automatically refreshes tokens 5 minutes before expiry
• Rate limits: freee API has rate limits (3,600 requests/hour). Use aggregated report APIs to minimize calls
• Company ID required: Most operations require a company ID. Set FREEE_DEFAULT_COMPANY_ID to avoid specifying it each time

License

MIT

Support

For issues related to:

• This MCP server: Create an issue in this repository
• freee API: Consult freee Developers Community
• MCP protocol: See MCP documentation