Firefly III MCP Server

AI 어시스턴트에게 Model Context Protocol을 통해 여러분 자신의 Firefly III 인스턴스에 대한 읽기 — 그리고 허용한다면 쓰기 — 액세스를 제공하세요.

26개 엔티티에 걸친 146개 작업: 거래, 계좌, 예산, 카테고리, 태그, 청구서, 돼지 저금통, 규칙, 그리고 검색 및 기간 분석.

터키어: README.tr.md

모든 사람은 이 서버를 자신의 Firefly 인스턴스와 자신의 토큰으로 실행합니다. 어떤 것도 공유되지 않으며, 어떤 데이터도 제3자를 거치지 않습니다.

설치

Node.js 20.6+가 필요합니다. 가장 빠른 방법은 설정 프로그램이 처리하게 하는 것입니다:

npx -y @yakupemreyerli/firefly-mcp setup

이 설정 프로그램은 Firefly III 주소와 API 토큰을 묻고, 해당 정보가 인스턴스에서 실제로 작동하는지 확인한 다음, Claude Code와 Claude Desktop을 발견하면 이를 구성합니다. — 건드리는 모든 것을 백업하고 다른 MCP 서버는 그대로 둡니다. 다른 클라이언트의 경우 붙여넣을 구성을 출력합니다.

직접 하고 싶다면:

Claude Code

claude mcp add firefly \
  --env FIREFLY_API_URL=your-firefly.example \
  --env FIREFLY_API_TOKEN=your-token \
  -- npx -y @yakupemreyerli/firefly-mcp

Claude Desktop, Cursor 및 기타 클라이언트

이 내용을 클라이언트의 MCP 구성 파일에 추가하세요:

{
  "mcpServers": {
    "firefly": {
      "command": "npx",
      "args": ["-y", "@yakupemreyerli/firefly-mcp"],
      "env": {
        "FIREFLY_API_URL": "your-firefly.example",
        "FIREFLY_API_TOKEN": "your-token"
      }
    }
  }
}

Firefly III → 옵션 → 프로필 → OAuth → 새 개인 액세스 토큰 만들기에서 토큰을 받으세요. URL의 경우 도메인만으로 충분합니다. — https://와 /api/v1은 자동으로 채워집니다. 인스턴스가 하위 경로, 사용자 지정 포트 또는 일반 http 뒤에 있다면 전체 URL을 입력하세요.

Related MCP server: Firefly III MCP Server

어디까지 가능한가

stdio에서는 Firefly 토큰이 허용하는 범위까지 가능합니다. 어시스턴트에게 구매를 기록하거나 거래를 분류하도록 요청할 수 있으며, 실제로 그렇게 합니다. 서버 전체 권한 설정은 없습니다. — 질문에만 답할 수 있는 세션이 필요하다면 Firefly III에서 읽기 전용 개인 액세스 토큰을 발급하세요. 그러면 제한은 같은 사람이 편집할 수 있는 변수가 아니라 Firefly가 강제합니다.

OAuth를 통한 HTTP에서는 액세스가 연결별로 결정됩니다. firefly:read, firefly:write, firefly:destructive는 비밀번호 화면에서 부여되며, 부여되지 않은 영역은 거부될 뿐만 아니라 숨겨집니다.

어시스턴트가 보는 것

도구는 146개가 아니라 다섯 개입니다. — 그리고 실행은 위험도에 따라 나뉘어 있어, 호스트는 잔액 읽기와 거래 삭제를 구분할 수 있습니다:

각 도구에는 MCP 도구 주석(readOnlyHint, destructiveHint, idempotentHint)이 있으며, 이러한 구분은 단순히 표시만 되는 것이 아니라 강제됩니다. firefly_query를 통해 도달한 삭제는 거부됩니다. firefly:read만 부여된 연결은 두 쓰기 도구를 전혀 볼 수 없습니다.

대부분의 MCP 클라이언트는 도구가 약 40개를 넘어가면 성능이 저하되므로, 노출 표면은 세 가지입니다.

응답은 모델에 도달하기 전에 다듬어집니다. 빈 속성과 null 속성은 항상 제거되며, 모든 실행 도구는 사용자가 지정한 속성만 유지하는 fields 목록을 받습니다. — 대규모 거래 목록의 경우 약 90%가 줄어듭니다.

구성

원격 HTTP 모드

프로세스를 실행하는 대신 HTTP로 연결하는 클라이언트(예: n8n)를 위해, 동일한 서버가 스트리밍 가능한 HTTP를 지원합니다:

export MCP_HTTP_TOKEN=$(openssl rand -hex 32)
npx -y -p @yakupemreyerli/firefly-mcp firefly-mcp-http

firefly-mcp-http는 같은 패키지 안에 있는 두 번째 바이너리입니다. 그래서 npx는 패키지와 명령을 따로 지정하기 위해 -p가 필요합니다.

MCP_HTTP_TOKEN 없이는 시작되지 않으며, /mcp에 대한 모든 요청은 Authorization: Bearer <token>을 포함해야 합니다. /health는 컨테이너 프로브를 위해 열려 있습니다. Dockerfile과 compose.example.yml은 리포지토리에 있습니다.

TLS 뒤에 두세요. 토큰은 인터넷과 금융 내역에 대한 쓰기 액세스 사이의 유일한 장벽입니다. — 포트를 직접 노출하지 마세요.

문서

Docker

HTTP 모드용으로 미리 빌드된 이미지가 있으며, linux/amd64 및 linux/arm64를 지원합니다:

docker run -d \
  -e FIREFLY_API_URL=your-firefly.example \
  -e FIREFLY_API_TOKEN=your-token \
  -e MCP_HTTP_HOST=0.0.0.0 \
  -e MCP_HTTP_TOKEN="$(openssl rand -hex 32)" \
  -p 3000:3000 \
  ghcr.io/yakupemreyerli/mcp-firefly-iii:latest

/health는 컨테이너 프로브를 위해 토큰 없이 응답합니다. /mcp의 모든 항목은 Authorization: Bearer <MCP_HTTP_TOKEN>이 필요합니다.

의존하는 항목에는 :latest 대신 버전(:0.3.1)을 고정하세요.

개발

git clone https://github.com/YakupEmreYerli/mcp-firefly-iii.git
cd mcp-firefly-iii
npm install
cp .env.example .env    # fill in your instance
npm test                # mocked; never touches a live instance
npm run build
npm run check           # read-only connection check against .env

테스트는 모의(mock) 처리되며 네트워크에 도달하지 않습니다. npm run smoke:live는 .env의 인스턴스를 대상으로 모든 읽기 작업을 실행하는 관리자용 도구입니다. 읽기 전용이며 게시된 패키지에는 포함되지 않습니다.

기여

버그 리포트와 풀 리퀘스트를 환영합니다. 코드 구조, 테스트 실행 방법, 그리고 무엇이든 건드리기 전에 알아두면 좋은 Firefly III 특이점은 CONTRIBUTING.md를 참조하세요.

보안 문제를 발견하셨나요? 비공개로 신고해 주세요 — SECURITY.md를 참조하세요.

라이선스

MIT — LICENSE 참조.