freee

freee-mcp

Servidor MCP oficial e Agent Skills da freee que permitem operar, a partir de um Agente de IA, os serviços de contabilidade (freee会計), RH e folha de pagamento (人事労務), faturamento (請求書), gestão de horas (工数管理), vendas (販売), gestão de TI (IT管理), ativos fixos (固定資産), gestão de terceirização (業務委託管理), pesquisas (サーベイ), abertura de empresa (開業), avaliação de desempenho (人事評価), declarações fiscais (申告) e assinatura eletrônica (サイン).

• Servidor MCP: responsável pela chamada, autenticação e validação de requisições da API freee
• Agent Skills: injeta referências de API e receitas de operação no contexto do Agente de IA, guiando o uso correto da API

Recursos

• Suporte a múltiplas APIs: suporta 12 APIs freee — contabilidade, RH e folha, faturamento, gestão de horas, vendas, gestão de TI, ativos fixos, gestão de terceirização, pesquisas, abertura de empresa, avaliação de desempenho e declarações fiscais
• Quantidade de operações suportadas: 515 operações (incluindo assinatura eletrônica; scripts/generate-references.ts é atualizado automaticamente)
• Condições de uso: pesquisas, abertura de empresa, avaliação de desempenho e declarações fiscais exigem ambiente de conexão, cliente OAuth, plano contratual e permissões de usuário correspondentes
• Suporte a assinatura eletrônica (サイン): a API de gestão de documentos do freee サイン é suportada por comando dedicado (freee-sign-mcp)
• OAuth 2.0 + PKCE: fluxo de autenticação seguro, com renovação automática de tokens
• Suporte a múltiplas empresas: permite alternância dinâmica entre empresas

Fluxo de comunicação entre Agent Skills e MCP

Utilize em conjunto os Agent Skills (referências de API e receitas de operação) e o servidor MCP (chamadas de API).

sequenceDiagram
    participant User as ユーザー
    participant Agent as AI Agent
    participant Skill as Agent Skills<br/>(API リファレンス・操作レシピ)
    participant MCP as MCP サーバー
    participant API as freee API

    User->>Agent: リクエスト<br/>「取引一覧を取得して」

    Note over Agent,Skill: 1. Agent Skills からリファレンスを取得
    Agent->>Skill: freee-api-skill 呼び出し
    Skill-->>Agent: API リファレンス注入<br/>(エンドポイント、パラメータ仕様)

    Note over Agent,MCP: 2. MCP Tool で API を実行
    Agent->>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-->>Agent: 取引データ
    Agent-->>User: 結果を整形して表示

Com esse mecanismo:

• Agent Skills: injeta gradualmente no contexto as referências de API e receitas de operação necessárias (eficiência de contexto)
• MCP: responsável por autenticação, validação de requisições e chamadas de API

Início rápido

Método 1: Conectar via Remote MCP (recomendado)

Conecte-se ao servidor Remote MCP fornecido pela freee. Não é necessária configuração local e você pode começar a usar imediatamente.

No Claude e no Claude Desktop, abra "Personalizar" > "Adicionar conector personalizado" e configure o seguinte:

• Nome: freee
• URL: https://mcp.freee.co.jp/mcp

⚠️ Tenha cuidado para não inserir URLs que não sejam oficiais da freee.

Em outras ferramentas de IA, adicione o servidor Remote MCP seguindo as instruções de cada uma.

Método 2: Iniciar o servidor MCP localmente

Registre seu próprio aplicativo freee e inicie o servidor MCP localmente.

2-1. Registro do aplicativo freee

Crie um novo aplicativo no freee アプリストア:

• URL de callback: http://127.0.0.1:54321/callback
• Obtenha o Client ID e o Client Secret
• Marque as permissões necessárias

2-2. Configuração

npx freee-mcp configure

O assistente interativo realiza a configuração das credenciais, a autenticação OAuth e a seleção da empresa.

2-3. Adicionar ao Claude Desktop

Adicione a configuração gerada por configure ao arquivo de configuração do Claude Desktop:

{
  "mcpServers": {
    "freee": {
      "command": "npx",
      "args": ["freee-mcp"]
    }
  }
}

Se você usa o Claude Desktop da Windows Store (Microsoft Store), o caminho do arquivo de configuração é diferente. freee-mcp configure detecta automaticamente o caminho adequado.

Instalar os Agent Skills

No Claude e no Claude Desktop, abra "Personalizar" > "Skills", baixe o freee-api-skill.zip mais recente e faça o upload.

• Baixar a versão mais recente (freee-api-skill.zip)
• Escolher pelo histórico de versões: página de Releases

Em agentes de codificação como Claude Code (Cursor, OpenCode etc.), é possível instalar via skills.

npx skills add freee/freee-mcp

Também é possível fazer instalação global (-g) ou instalar apenas skills específicos (-s).

Também é possível instalar pelo comando gh skill do GitHub CLI (v2.90.0 ou superior).

gh skill install freee/freee-mcp freee-api-skill

Há suporte para especificar --agent (ex.: claude-code, copilot, cursor, codex, gemini-cli), --scope user／--scope project, e fixação em tag/commit específico via --pin.

Se você utiliza o Agent Package Manager (APM), também é possível instalar com o comando abaixo. A implantação é feita automaticamente nos diretórios de destino do projeto, como GitHub Copilot / Claude Code / Cursor / OpenCode / Codex.

apm install freee/freee-mcp/skills/freee-api-skill

Usar como plugin do Claude Code

Ao instalar como plugin no Claude Code, o servidor MCP e os Agent Skills (referências de API e receitas de operação) ficam disponíveis em conjunto.

Execute os dois comandos abaixo em sequência:

claude plugin marketplace add freee/freee-mcp
claude plugin install freee-mcp@freee-mcp-marketplace

Também é possível executar diretamente no prompt do Claude Code:

/plugin marketplace add freee/freee-mcp
/plugin install freee-mcp@freee-mcp-marketplace

Usar como plugin do Codex

Também há suporte ao marketplace de plugins do OpenAI Codex (documentação oficial), permitindo usar em conjunto o servidor MCP e os Agent Skills (referências de API e receitas de operação).

Adicione o marketplace pelo Codex CLI:

codex plugin marketplace add freee/freee-mcp

Em seguida, inicie o Codex, abra a lista de plugins com o comando de barra /plugins, selecione freee-mcp e execute Install plugin.

A definição do plugin está em .codex-plugin/plugin.json e o catálogo do marketplace está em .agents/plugins/marketplace.json.

Conteúdo dos Agent Skills

API	Conteúdo	Nº de arquivos
Contabilidade	Transações, plano de contas, clientes/fornecedores, faturas, solicitações de despesas etc.	33
RH e folha	Funcionários, ponto, contracheques, ajuste anual etc.	28
Faturamento	Faturas, orçamentos, notas de entrega, recibos, ordens de compra, avisos de pagamento	6
Gestão de horas	Projetos, equipes, parceiros, horas, usuários etc.	9
Vendas	Oportunidades, pedidos, cadastros	13
Gestão de TI	Membros, contas SaaS, equipamentos	3
Ativos fixos	Lista, detalhes, cadastro, atualização e exclusão de ativos fixos	1
Gestão de terceirização	Usuários corporativos, departamentos e clientes/fornecedores de terceirizados	3
Pesquisas	Planejamento e execução de pesquisas (somente versão remota do freee-mcp)	1
Abertura de empresa	Dados para solicitação de abertura (somente versão remota do freee-mcp)	1
Avaliação de desempenho	Resultados de avaliação de desempenho (somente versão remota do freee-mcp)	1
Declarações fiscais	Dados de declaração de imposto corporativo, formulários (anexos, demonstrações financeiras etc.)	58
Assinatura	Documentos, pastas, modelos, carimbo pessoal etc.	8

Ao solicitar operações da API freee durante uma conversa com o Agente de IA, ele consulta essas referências e receitas para executar com precisão.

Boas práticas para criação de dados

Ao criar repetidamente dados com o mesmo formato, como faturas e reembolsos de despesas, é possível trabalhar com mais eficiência consultando dados criados anteriormente:

• Criação de faturas: recupere faturas anteriores e use como referência para cliente/fornecedor, itens, classificação fiscal etc.
• Reembolso de despesas: consulte solicitações anteriores para especificar corretamente contas contábeis e departamentos
• Registro de transações: use transações semelhantes como referência para evitar erros de digitação

例: 「先月の○○社への請求書を参考に、今月分を作成して」

Ferramentas disponíveis

Ferramentas de administração

Ferramenta	Descrição	Observações
freee_authenticate	Executa autenticação OAuth	Somente stdio
freee_auth_status	Verifica o estado da autenticação
freee_clear_auth	Limpa as credenciais de autenticação
freee_set_current_company	Alterna a empresa
freee_get_current_company	Exibe a empresa atual
freee_list_companies	Obtém a lista de empresas
freee_current_user	Informações do usuário atual
freee_server_info	Obtém informações do servidor
freee_file_upload	Upload de arquivos	Somente stdio

Ferramentas de API

Estrutura simples de ferramentas por método HTTP:

Ferramenta	Descrição	Exemplo
freee_api_get	Obter dados	/api/1/deals
freee_api_post	Criar novo	/api/1/deals
freee_api_put	Atualizar	/api/1/deals/123
freee_api_delete	Excluir	/api/1/deals/123
freee_api_patch	Atualização parcial	/api/1/deals/123
freee_api_list_paths	Lista de endpoints	-

Os caminhos são validados automaticamente contra o esquema OpenAPI.

freee サイン (assinatura eletrônica)

A API do freee サイン pode ser usada com o comando dedicado freee-sign-mcp.

A disponibilização via Remote MCP está em preparação. Atualmente, apenas o servidor MCP local é suportado.

Configuração

npx --package=freee-mcp -- freee-sign-mcp configure

O assistente interativo realiza a configuração das credenciais e a autenticação OAuth.

Configuração do MCP

{
  "mcpServers": {
    "freee-sign-mcp": {
      "command": "npx",
      "args": ["--package=freee-mcp", "--", "freee-sign-mcp"]
    }
  }
}

Ferramentas para assinatura

Ferramenta	Descrição
sign_authenticate	Executa autenticação OAuth
sign_auth_status	Verifica o estado da autenticação
sign_clear_auth	Limpa as credenciais de autenticação
sign_api_get	Obter dados
sign_api_post	Criar novo
sign_api_put	Atualizar
sign_api_patch	Atualização parcial
sign_api_delete	Excluir

Tratamento do company_id

Se a requisição (parâmetro ou corpo) incluir company_id, ele deve corresponder à empresa atual. Caso contrário, ocorrerá um erro.

• Verificar a empresa: freee_get_current_company
• Alternar a empresa: freee_set_current_company
• APIs que não incluem company_id (ex.: /api/1/companies) podem ser executadas normalmente

Contribuição

Consulte CONTRIBUTING.md para mais detalhes.

Contribuidores

Para desenvolvedores

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

bun run dev           # 開発サーバー（ウォッチモード）
bun run build         # ビルド
bun run typecheck    # 型チェック
bun run lint          # リント
bun run test:run      # テスト

# API リファレンスの再生成
bun run generate:references

# OpenAPI スキーマの操作数・パス数を集計（プロダクト別の内訳も表示）
bun run count:apis

Stack tecnológico

TypeScript / Model Context Protocol SDK / OAuth 2.0 + PKCE / Zod / Bun

Detalhes da arquitetura

Consulte CLAUDE.md para arquitetura do projeto, estrutura interna e diretrizes de desenvolvimento.

Licença

Apache-2.0

Comunidade

Dúvidas e troca de informações acontecem no servidor Discord. Sinta-se à vontade para participar.

• Servidor Discord

Links relacionados

• Artigo de apresentação: Por que combinar Agent Skills ao transformar a Public API em MCP — com freee-mcp
• Documentação da API freee
• Model Context Protocol