Firefly III MCP Server

Firefly III를 위한 Model Context Protocol(MCP) 서버입니다. Firefly III는 무료 오픈소스 개인 재무 관리자이며, 이 MCP 서버를 통해 사용자는 AI 도구를 활용해 Firefly III 계정과 거래를 관리하고, 개인 재무 및 회계를 위한 AI 어시스턴트를 만들 수 있습니다.

중국어 버전 보기

프로젝트 구조

이 프로젝트는 Turborepo로 관리되는 모노레포 구조를 사용하며, 주요 패키지는 다음과 같습니다.

• @firefly-iii-mcp/core — Firefly III API 상호작용의 기반을 제공하는 핵심 기능 모듈

• @firefly-iii-mcp/local — MCP 서버를 로컬에서 실행하기 위한 명령줄 도구

• @firefly-iii-mcp/cloudflare-worker — Cloudflare Workers 배포용 구현

• @firefly-iii-mcp/server — Streamable HTTP 및 SSE를 지원하는 Express 기반 서버 구현

Related MCP server: Firefly III MCP Server

기능

• AI를 통해 Firefly III 인스턴스와 상호작용

• 계정 및 거래를 프로그래밍 방식으로 관리

• 다양한 금융 작업을 위한 확장 가능한 도구 세트

• 로컬 및 클라우드 배포 지원

• Model Context Protocol 표준 호환

• 프리셋 또는 사용자 지정 태그로 도구를 필터링하여 토큰 사용량 절감

사전 요구 사항

• 실행 중인 Firefly III 인스턴스

• "Deploy to Cloudflare" 버튼을 이용해 배포하려는 경우 Cloudflare 계정이 필요합니다.

시작하기

1. Firefly III 개인 액세스 토큰(PAT) 발급

MCP 서버가 Firefly III 인스턴스와 상호작용할 수 있도록 개인 액세스 토큰(PAT)을 발급해야 합니다.

1. Firefly III 인스턴스에 로그인합니다.

2. Options > Profile > OAuth로 이동합니다.

3. "Personal access tokens" 섹션에서 "Create new token"을 클릭합니다.

4. 토큰에 설명이 포함된 이름을 지정합니다(예: "MCP Server Token").

5. "Create"를 클릭합니다.

6. 중요: 생성된 토큰은 즉시 복사하세요. 이후 다시 확인할 수 없습니다.

자세한 내용은 Personal Access Tokens 공식 문서를 참조하세요.

2. MCP 서버 구성

MCP 서버에 Firefly III PAT와 인스턴스 URL을 제공해야 합니다. 구성 방법은 여러 가지입니다.

요청 헤더 (권장)

MCP 서버에 전송하는 각 요청 헤더에 다음 값을 넣는 방식으로, 일반적으로 가장 안전합니다.

• X-Firefly-III-Url: Firefly III 인스턴스 URL (예: https://firefly.yourdomain.com)

• Authorization: 일반적으로 Bearer 접두사를 붙이는 개인 액세스 토큰 (예: Bearer YOUR_FIREFLY_III_PAT)

정확한 헤더 이름은 사용 중인 AI 도구 또는 클라이언트 문서를 참조하세요.

쿼리 매개변수 (주의해서 사용)

MCP 서버에 전송하는 각 요청의 쿼리 매개변수로 값을 제공할 수도 있습니다.

• baseUrl: Firefly III 인스턴스 URL

• pat: Firefly III 개인 액세스 토큰

쿼리 매개변수를 포함한 URL은 여러 곳에 로그로 기록될 수 있으므로 민감한 정보가 노출될 가능성이 있음을 유의하세요.

환경 변수 (주로 자체 호스팅/로컬 개발용)

서버를 실행하기 전에 다음 환경 변수를 설정합니다.

FIREFLY_III_BASE_URL="YOUR_FIREFLY_III_INSTANCE_URL" # e.g., https://firefly.yourdomain.com
FIREFLY_III_PAT="YOUR_FIREFLY_III_PAT"
# Optional: Filter tools using preset or custom tags
FIREFLY_III_PRESET="default" # Available: default, full, basic, budget, reporting, admin, automation
# Or specify custom tool tags (overrides preset if both are set)
FIREFLY_III_TOOLS="accounts,transactions,categories"

MCP 서버 실행

방법 1: 로컬 모드

이 방법은 Claude Desktop과 같이 표준 입출력(stdio)으로 MCP 도구를 호출하는 클라이언트에 적합합니다.

기본 실행 명령입니다.

npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL

토큰 사용량을 줄이기 위해 도구를 필터링할 수도 있습니다.

# Using a preset
npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL --preset budget

# Using custom tool tags
npx @firefly-iii-mcp/local --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL --tools accounts,transactions,categories

JSON 형식을 구성하는 방법은 공식 튜토리얼을 참조할 수 있습니다.

{
  "mcpServers": {
    "firefly-iii": {
      "command": "npx",
      "args": [
        "@firefly-iii-mcp/local",
        "--pat",
        "<Your Firefly III Personal Access Token>",
        "--baseUrl",
        "<Your Firefly III Base URL>",
        "--preset",
        "default"
      ]
    }
  }
}

방법 2: Express 서버 (웹 앱에 권장)

Streamable HTTP와 SSE를 지원하는 HTTP 기반 서버를 제공하며 웹 애플리케이션에 적합합니다.

명령줄 도구로 사용

npx @firefly-iii-mcp/server --pat YOUR_PAT --baseUrl YOUR_FIREFLY_III_URL

명령줄 옵션:

• -p, --pat <token> — Firefly III 개인 액세스 토큰

• -b, --baseUrl <url> — Firefly III 기본 URL

• -P, --port <number> — 수신 대기 포트 (기본값: 3000)

• -l, --logLevel <level> — 로그 레벨: debug, info, warn, error (기본값: info)

• -s, --preset <name> — 사용할 도구 프리셋 (default, full, basic, budget, reporting, admin, automation)

• -t, --tools <list> — 사용할 도구 태그를 쉼표로 구분한 목록

라이브러리로 사용

npm install @firefly-iii-mcp/server

기본 사용법입니다.

import { createServer } from '@firefly-iii-mcp/server';

const server = createServer({
  port: 3000,
  pat: process.env.FIREFLY_III_PAT,
  baseUrl: process.env.FIREFLY_III_BASE_URL,
  enableToolTags: ['accounts', 'transactions', 'categories'] // Optional: Filter available tools
});

server.start().then(() => {
  console.log('MCP Server is running on http://localhost:3000');
});

자세한 내용은 @firefly-iii-mcp/server 문서를 참조하세요.

방법 3: Cloudflare Workers에 배포 (프로덕션 권장)

아래 버튼을 누르면 이 MCP 서버를 Cloudflare Workers에 쉽게 배포할 수 있습니다.

참고: 배포 후 Cloudflare Worker 설정에서 환경 변수를 구성해야 합니다.

1. Cloudflare 대시보드로 이동합니다.

2. Workers & Pages로 이동합니다.

3. 배포한 Worker를 선택합니다.

4. Settings > Variables로 이동합니다.

5. 다음 변수를 추가합니다.

   • 필수: FIREFLY_III_BASE_URL, FLY_III_PAT

   • 선택: FIREFLY_III_PRESET 또는 FLY_III_TOOLS

방법 4: 소스에서 로컬 실행

[!NOTE] 운영 환경에서는 NPM 패키지 또는 Cloudflare Workers에 배포하는 것을 권장합니다.

1. 저장소를 클론합니다.

   git clone https://github.com/etnperlong/firefly-iii-mcp.git
   cd firefly-iii-mcp

2. 의존성을 설치합니다.

   npm install

3. .env 파일을 생성합니다.

   FIREFLY_III_BASE_URL="YOUR_FIREFLY_III_INSTANCE_URL"
   FIREFLY_III_PAT="YOUR_FIREFLY_III_PAT"
   # Optional: Filter tools
   FIREFLY_III_PRESET="default"
   # Or
   FIREFLY_III_TOOLS="accounts,transactions,categories"

4. 프로젝트를 빌드합니다.

   npm run build

5. 개발 서버를 실행합니다.

   npm run dev

도구 필터링 옵션

MCP 클라이언트에 노출되는 도구를 필터링하면 토큰 사용량을 줄이고 특정 기능에 집중할 수 있습니다.

사용 가능한 프리셋

• default: 일상적 사용에 필요한 기본 도구 (계정, 청구서, 카테고리, 태그, 거래, 검색, 요약)

• full: 전체 도구

• basic: 핵심 금융 관리 도구

• budget: 예산 중심 도구

• reporting: 보고 및 분석 도구

• admin: 관리 도구

• automation: 자동화 관련 도구

개발 가이드

이 프로젝트는 Turborepo로 모노레포 워크플로를 관리하며, 버전 관리 및 패키지 배포는 Changesets로 합니다.

일반적인 명령어

• npm run build: 전체 패키지 빌드

• npm run build:core / npm run build:local: 특정 패키지 빌드

• npm run clean: 빌드 산출물 정리

• npm run dev: 개발 모드 실행

• npm run publish-packages: 패키지 배포

자세한 개발 지침은 기여 가이드를 참조하세요.

감사의 말

이 프로젝트는 harsha-iiiv/openapi-mcp-generator의 생성 스크립트를 사용하여 수정하였습니다. 원저자에게 감사합니다.

기여

컨트리뷰션을 환영합니다. 이 프로젝트는 Turborepo로 모노레포 워크플로우를 관리하며, 기여 방법은 CONTRIBUTING.md를 참조하세요.

라이선스

이 프로젝트는 MIT 라이선스에 따라 배포됩니다.