freee/freee-mcp

개요

freee‑mcp는 AI 에이전트(Claude, Codex, Cursor 등)가 freee 비즈니스 소프트웨어 플랫폼과 통신할 수 있게 해주는 공식 브리지입니다. 두 부분으로 구성됩니다:

MCP 서버 – OAuth 2.0 + PKCE 인증을 처리하고, freee의 OpenAPI 사양에 대해 요청을 검증하며, freee REST API로 호출을 전달하는 작은 Node.js 서비스입니다.
Agent Skills – 각 freee 엔드포인트(매개변수, 요청 형식, 예제)를 설명하는 JSON/YAML "레시피" 모음입니다. 에이전트가 "지난 달 청구서 보여줘" 같은 사용자 요청을 받으면 관련 스킬을 가져와 올바른 API 호출을 구성하고 MCP 서버로 보냅니다.

요컨대, 자연어 명령을 인증된 freee API 호출로 변환하여 회계, 인사, 청구, 프로젝트 시간 추적, 영업, IT 자산 관리, 전자 계약 등을 다룹니다.

누가 사용할까요?

역할	중요성
비즈니스 분석가 / 재무 팀	코드를 작성하지 않고 LLM에 거래, 청구서, 급여 데이터를 가져오거나 생성하도록 요청할 수 있습니다.
AI 증강 봇을 개발하는 개발자	MCP 서버를 Claude Code, OpenAI Codex, Cursor 등에 연결하고 봇에 freee의 12개 모듈 API에 대한 액세스를 즉시 제공합니다.
자동화 엔지니어	CLI 도구(`freee_api_get`, `freee_api_post` 등)를 사용하여 일괄 작업을 스크립팅하면서 OpenAPI 검증의 이점을 누릴 수 있습니다.
freee 파트너 및 ISV	OAuth 또는 요청 검증을 다시 구현하지 않고 제품에 "freee에 말하기" 기능을 제공합니다.

작동 방식 (높은 수준의 흐름)

설정 – freee 애플리케이션을 등록하고, npx freee-mcp configure를 실행하거나(또는 호스팅된 Remote MCP에 연결) 마법사가 클라이언트 ID, 시크릿을 저장하고 기본 회사를 선택합니다.
에이전트가 스킬 요청 – LLM이 freee-api-skill 패키지를 호출하여 엔드포인트 정의와 짧은 "레시피"를 반환합니다.
에이전트가 요청 구성 – 레시피를 사용하여 에이전트는 freee_api_get('/api/1/deals') 같은 호출을 구성합니다.
MCP 서버 검증 – OpenAPI 스키마에 대해 요청을 확인하고, OAuth 베어러 토큰을 추가하고, https://api.freee.co.jp로 전달합니다.
응답 반환 – MCP 서버가 JSON을 에이전트에 전달하고, 에이전트는 사람이 읽을 수 있는 답변으로 형식화합니다.

모든 인증은 자동으로 처리되며 토큰은 필요에 따라 갱신됩니다.

주요 기능

광범위한 API 커버리지 – 12개 freee 모듈, 557개의 개별 작업(전자 계약 freee-sign 명령 포함).
안전한 OAuth 2.0 + PKCE – 시크릿은 평문으로 저장되지 않으며 서버가 토큰을 갱신합니다.
동적 회사 전환 – freee_set_current_company를 통해 단일 MCP 인스턴스로 여러 비즈니스 위치에서 작업할 수 있습니다.
OpenAPI 기반 검증 – 모든 요청은 freee의 공식 스키마에 대해 확인되어 잘못된 호출을 방지합니다.
원격 또는 로컬 MCP – 호스팅된 서버(https://mcp.freee.co.jp/mcp)를 사용하여 즉시 시작하거나 Node 서버를 직접 실행하여 완전한 제어가 가능합니다.
준비된 Agent Skills – ZIP 파일(freee-api-skill.zip)에 전체 참조 세트가 포함되어 있으며 Claude, skills, GitHub CLI 또는 Microsoft APM을 통해 설치할 수 있습니다.
CLI 도구 상자 – 수동 테스트 또는 스크립팅을 위한 간단한 명령(freee_api_get, freee_api_post, freee_file_upload 등).
freee Sign 지원 – 전자 계약 관리를 위한 전용 freee-sign-mcp 명령 세트(현재 로컬 전용).

시작하기 (빠른 단계)

연결 모드 선택
- 원격: Claude Desktop → 사용자 지정 커넥터 → 이름 freee, URL https://mcp.freee.co.jp/mcp.
- 로컬: freee 개발자 포털에서 앱을 등록한 다음 npx freee-mcp configure를 실행합니다.
스킬 추가
- 최신 릴리스에서 freee-api-skill.zip을 다운로드하여 Claude Desktop의 Skills UI에 업로드하거나 npx skills add freee/freee-mcp를 실행합니다.
명령 테스트
```
npx freee_api_get /api/1/deals
```
CLI가 인증하고 API를 호출하고 JSON 응답을 출력합니다.
LLM에서 사용
- Claude에서 "Acme Corp의 새 청구서를 만들어 주세요, 15만 엔, 다음 주 금요일 마감"이라고 요청합니다. 에이전트가 적절한 스킬을 가져와 freee_api_post /api/1/invoices를 호출하고 생성을 확인합니다.

누가 만들었는지 및 기여 방법

freee Inc.가 유지 관리 – 공식 오픈 소스 프로젝트(Apache-2.0). 리포지토리에는 30명 이상의 기여자가 있습니다.
개발 워크플로우 – bun이 패키지 매니저이며 일반적인 명령은 bun run dev, bun run build, bun run test:run 등입니다.
확장 – 새 스킬 추가, bun run generate:references로 OpenAPI 참조 업데이트, 또는 풀 리퀘스트를 통한 버그 수정 기여. 자세한 내용은 CONTRIBUTING.md를 참조하세요.

TL;DR

freee-mcp = MCP 서버 + 스킬 번들로, AI 에이전트가 자연어 프롬프트를 통해 freee의 비즈니스 소프트웨어 API(회계, 인사, 청구, 계약 등)를 안전하게 호출할 수 있게 합니다. 원격 서버를 설치하거나 로컬에서 실행하고, LLM에 스킬 패키지를 추가하고, 대화형 인터페이스로 freee 작업 자동화를 시작하세요.