pluggy-mcp-server

읽기 전용 MCP 서버로, 개인 금융 데이터(브라질 오픈 파이낸스, Pluggy 경유)를 모든 MCP 클라이언트 — Claude Code, Cursor, Cline, Zed — 에 노출합니다.

유료 "은행 MCP 서비스"의 자체 호스팅 대안: Meu Pluggy는 API를 통해 자신의 데이터에 접근하는 개인에게 무료이며 만료일이 없습니다.

자금 이동 없음. PIX, 송금, 결제 기능이 없습니다. Pluggy의 PaymentsClient는 절대 임포트되지 않으며, 누군가 임포트하면 테스트가 실패합니다.

도구

금액은 음수가 항상 계좌에서 돈이 나가는 것을 의미하도록 정규화되며, 은행 계좌와 신용카드 모두에 적용됩니다. Pluggy의 원시 데이터는 두 경우가 서로 달라, 카드 지출과 은행 지출을 단순 합산하면 상쇄됩니다. 또한 항상 계좌 고유 통화로 표시됩니다: Pluggy는 해외 구매를 가맹점 통화로 보고하므로, 환산된 값이 사용되고 원래 값은 valor_orig에 보관되어 대사(對査)에 사용됩니다.

모든 계좌가 헤알(real) 단위인 것은 아닙니다. list_accounts, list_investments, list_investment_transactions는 모두 currency 열을 포함합니다. 해외 중개사가 브라질 계좌 옆에 USD 잔액과 포지션을 보고하기 때문입니다. 순자산과 포트폴리오 합계는 환산하지 않고 명시하지 않는 한 통화별로만 의미가 있습니다.

신용카드에서 date는 구매일이 아닌 게시일입니다 — 1년 전 구매의 할부가 이번 달에 게시될 수 있습니다. data_compra는 두 날짜가 다를 때 원래 날짜를 담고, fatura는 해당 행이 속한 청구서를 나타내므로 list_transactions({ bill })는 청구서 총액의 세부 항목을 반환합니다.

Related MCP server: @gu-does-packages/pluggy-mcp

프롬프트

저장된 분석으로, 매달 같은 질문을 같은 방식으로 묻습니다.

설정

1. 은행 연결 (1회, 약 15분)

1. meu.pluggy.ai에서 계정을 만들고 은행을 연결하세요

2. dashboard.pluggy.ai에서 계정을 만드세요. 15일 평가판이 시작되지만 무시해도 됩니다: Pluggy는 만료 후에도 데이터를 가져올 수 있다고 명시합니다

3. 애플리케이션을 만들기 전에 Customize로 이동하여 커넥터 목록에 MeuPluggy 커넥터를 추가하세요. 건너뛰면 나중에 표시되지 않습니다

4. Development Application을 만들고 Client ID와 Client Secret을 복사하세요

5. Demo 애플리케이션을 열고 MeuPluggy OAuth 인증을 통해 Meu Pluggy 계정을 연결하세요. 연결된 은행마다 이 작업을 반복하세요 — Pluggy는 계좌가 아닌 은행별로 하나의 item을 발급합니다

6. 각 연결의 Item ID를 복사하세요("Copiar Item ID")

연결 이름은 Pluggy가 보고하는 계좌 이름에서 파생되므로 새 은행은 구성이 필요 없습니다. 어떤 item도 기관 이름을 지정하지 않는 경우 — 일부는 모든 계좌를 Conta Corrente로 보고합니다 — PLUGGY_ITEM_LABELS=<item id>=Banco X로 직접 이름을 지정하고, 여러 개는 쉼표로 구분하세요.

커넥터 200은 Meu Pluggy가 소유한 연결에 대한 프록시 역할을 하며 매일 새로 고칩니다. Meu Pluggy가 소유하므로 Pluggy는 API를 통한 동기화를 거부합니다 — refresh_connection은 400 MeuPluggy item cant be updated로 응답하고 대신 어디로 가야 하는지 알려줍니다. 강제 업데이트는 meu.pluggy.ai에서 은행을 다시 연결하는 것을 의미하며, 기록에서 누락된 기간은 은행이 여전히 오픈 파이낸스로 노출하는 경우에만 다시 나타납니다.

2. 커넥터 200이 실제로 반환하는 것 확인

npm install
npm run setup   # prompts for the credentials, writes .env with mode 0600
npm run probe

npm run setup은 입력하는 동안 클라이언트 시크릿을 마스킹하고, MCP 베어러 토큰을 생성하며, 아무것도 쓰기 전에 Pluggy API에 대해 자격 증명을 검증합니다. 다시 실행하면 현재 값을 유지합니다 — 프롬프트에서 Enter를 눌러 건너뛰세요.

프로브는 투자, 신용카드 청구서, 대출이 연결에서 사용 가능한지 보고하고 날짜 및 카테고리 처리를 검증합니다. 계좌 번호, 세금 ID, 거래 설명은 출력하지 않습니다.

3. 실행

npm run dev            # development, reads .env directly
npm run build && npm start   # production

curl localhost:8787/health로 작동하는지 확인하세요.

배포 (VM + Tailscale)

프로세스는 루프백에서만 수신합니다. 노출은 Tailscale이 처리하며 0.0.0.0 바인딩으로는 절대 처리하지 않습니다 — 클라우드 VM에는 공용 IP가 있고, 잘못된 바인딩과 열린 보안 목록이 결합되면 은행 명세서가 인터넷에 노출됩니다.

VM에는 Node 22.6+와 Tailscale이 이미 실행 중(tailscale up)이어야 합니다. 유닛 파일은 /usr/bin/node를 실행하는데, 이는 배포판 또는 NodeSource 패키지가 설치되는 위치입니다. nvm으로 Node를 설치했다면 ExecStart를 실제 바이너리로 지정하세요.

1. 서비스 계정 및 코드

서비스는 디스크에 절대 쓰지 않습니다 — 캐시는 메모리에 있으며, 유닛은 빈 ReadWritePaths로 ProtectSystem=strict를 설정합니다. 따라서 코드는 root가 소유하고 서비스 사용자는 읽기만 합니다: 손상된 프로세스는 자신의 소스를 다시 쓸 수 없습니다.

sudo useradd --system --no-create-home --shell /usr/sbin/nologin pluggy-mcp

sudo git clone https://github.com/brunopedrazza/pluggy-mcp-server /opt/pluggy-mcp
cd /opt/pluggy-mcp
sudo npm ci                  # dev dependencies included: tsc is needed to build
sudo npm run build
sudo npm prune --omit=dev    # and dropped again; free-tier VMs are small

2. 자격 증명

scp로 .env를 복사하는 대신 VM에서 설정을 실행하세요. 아무것도 쓰기 전에 Pluggy API에 대해 자격 증명을 검증하며, 이는 VM에 아웃바운드 연결이 있음을 증명합니다 — systemd가 개입하기 전에 알아두면 좋습니다.

sudo npm run setup

sudo install -d -m 700 /etc/pluggy-mcp
sudo install -m 600 .env /etc/pluggy-mcp/env
sudo rm /opt/pluggy-mcp/.env   # one copy of the secret, not two

3. 서비스

sudo cp deploy/pluggy-mcp.service /etc/systemd/system/
sudo systemctl enable --now pluggy-mcp

포트가 응답하는 것뿐만 아니라 Pluggy에 도달했는지 확인하세요:

curl localhost:8787/health
journalctl -u pluggy-mcp -n 20

저널은 transaction cache warmed로 끝나야 합니다. 대신 이름 확인 오류와 함께 cache warm failed가 표시되면 원인은 유닛의 RestrictAddressFamilies입니다: glibc가 systemd-resolved를 통해 확인하는 경우 getaddrinfo는 유닉스 소켓이 필요합니다. 해당 줄에 AF_UNIX를 추가하고 다시 시작하세요.

4. 테일넷에 게시

포트를 요청하기 전에 노드가 이미 게시하는 것을 확인하세요 — serve는 같은 포트와 경로의 핸들러를 경고 없이 교체하며, 이미 있는 서비스에서 443의 /를 가져가는 것은 조용한 중단입니다:

sudo tailscale serve status   # empty output means 443 is free

443이 비어 있으면 사용하세요. 이미 차지하고 있다면 경로를 공유하는 대신 다른 HTTPS 포트에 마운트하세요:

sudo tailscale serve --bg --https=8443 127.0.0.1:8787
sudo tailscale serve status   # prints the https://…ts.net URL used below

이를 위해서는 테일넷에 HTTPS가 활성화되어 있어야 합니다(관리 콘솔 > DNS). 인증서는 실제이며 자동으로 발급되므로 베어러 토큰이 평문으로 전송되지 않습니다. Serve 구성은 재부팅 후에도 유지되므로 일회성 명령입니다.

클라이언트 연결

claude mcp add --transport http pluggy https://YOUR-VM.YOUR-TAILNET.ts.net/mcp \
  --header "Authorization: Bearer $MCP_BEARER_TOKEN"

URL은 --header 앞에 와야 합니다. 해당 플래그는 가변 인수이므로 그 뒤의 모든 것은 다른 헤더로 구문 분석되고 URL은 위치 인수에 도달하지 않습니다.

로컬에서 npm run dev에 대해:

claude mcp add --transport http pluggy http://127.0.0.1:8787/mcp \
  --header "Authorization: Bearer $(grep '^MCP_BEARER_TOKEN=' .env | cut -d= -f2-)"

이는 Claude 웹 또는 모바일 앱에서는 작동하지 않습니다: claude.ai 사용자 지정 커넥터는 Anthropic의 인프라에서 다이얼되며, 이는 사설 테일넷에 도달할 수 없습니다. 실행 중인 머신에서 연결하는 클라이언트는 정상적으로 작동합니다.

업데이트

cd /opt/pluggy-mcp
sudo git pull && sudo npm ci && sudo npm run build && sudo npm prune --omit=dev
sudo systemctl restart pluggy-mcp

베어러 토큰 교체도 같은 재시작입니다: /etc/pluggy-mcp/env를 편집하고, 서비스를 재시작하고, 모든 클라이언트의 헤더를 업데이트하세요.

또는 시스템이 처리하도록 하세요: systemd 타이머가 origin/main을 추적하고, 이동 시 재빌드하며, 새 커밋이 정상으로 돌아오지 않으면 롤백할 수 있습니다. 복사할 파일 두 개 — deploy/README.md 참조.

설계

모든 결정과 그 근거는 DESIGN.md에 있습니다.

라이선스

MIT