plaid-mcp
plaid-mcp
일시적인 컨테이너에서 실행되는 AI 어시스턴트(Elowen)를 위한 지속형 Plaid MCP 서버입니다.
plaid-mcp는 Plaid 비밀 키와 연결된 모든 기관의 암호화된 액세스 토큰을 소유하는 장기 실행 외부 호스팅 서비스입니다. 어시스턴트는 런타임에 mcp__plaid__* 도구를 호출하며, 원시 액세스 토큰은 절대 볼 수 없고 Plaid가 이미 공개된 것으로 간주하는 불투명한 item_id 및 account_id 값만 확인합니다.
Elowen (ephemeral container)
└─ calls mcp__plaid__* tools
└─ plaid-mcp (persistent, nanoclaw-hosted)
├─ Plaid SDK + PLAID_SECRET (never leaves this service)
├─ access_token store (SQLite, AES-256-GCM at rest)
└─ /link/start, /link/callback (HTTPS, browser-facing)
└─ Plaid REST API / Plaid Link JS인터페이스
단일 Node.js 프로세스가 두 개의 완전히 분리된 인터페이스를 노출합니다:
MCP 서버.
stdio(에이전트가 이 바이너리를 하위 프로세스로 생성) 또는http(POST /mcp에서 스트리밍 HTTP, Bearer 인증) 중 하나를 선택합니다.MCP_TRANSPORT로 선택하십시오. 위에서 설명한 가계부 사용 사례의 경우, 여러 일시적 에이전트 컨테이너가 하나의 지속형 서버를 공유할 수 있도록http를 권장합니다.HTTPS 링크 미니 앱 (
/link/*). 일회성 은행 연결 흐름 중에만 사용됩니다. 사용자가 어시스턴트가 제공한 URL을 열고 Plaid Link 내에서 은행에 로그인하면 완료됩니다. 그 이후에는 해당 기관에 대해 브라우저가 다시 필요하지 않습니다.
Related MCP server: plaid-mcp
MCP 도구
도구 | 기능 |
|
|
| 하나 또는 모든 기관에 대한 캐시된 계좌 목록(유형, 하위 유형, 마스킹, 최종 잔액). |
|
|
| 날짜 범위별 거래 내역, 페이지당 약 250개, 불투명한 페이지네이션 커서. |
| 서버 측 필터링 거래 검색. 간결한 행 반환. |
|
|
| 포지션 스냅샷(티커, 수량, 시장 가치, 원가). |
| 특정 기간의 매수/매도/배당 내역. |
| 신용카드 APR/명세서, 학자금 대출, 모기지 세부 정보. |
|
|
|
|
| Plaid 항목을 취소하고 로컬 토큰을 삭제합니다. |
모든 도구 응답은 단일 text 콘텐츠 항목 내의 JSON입니다(structuredContent를 지원하지 않는 클라이언트를 포함한 모든 MCP 클라이언트에서 작동).
일회성 연결 흐름
Elowen이
initiate_link({ institution_hint: "Chase" })를 호출합니다. 서버는:Plaid
/link/token/create를 호출하고,link_sessions행을 저장하며(상태pending),{ url: "https://<LINK_BASE_URL>/link/start?s=<uuid>&sig=<hmac>", session_id, expires_at }를 반환합니다.
Elowen이 사용자에게 URL을 보냅니다.
사용자가 브라우저에서 URL을 엽니다. 페이지는 공식 CDN에서 해당
link_token으로 Plaid Link JS를 로드하고 "Open Plaid Link" 버튼을 표시합니다.Plaid Link의
onSuccess는{ public_token, institution }과 서명된 세션 ID를/link/callback으로 POST합니다./link/callback은public_token을access_token+item_id로 교환하고, 액세스 토큰을 AES-256-GCM으로 암호화하여 저장한 뒤 세션을succeeded로 표시합니다.Elowen이
link_status(session_id)를 폴링하여item_id와 함께succeeded상태를 확인하고 진행합니다.
서명된 URL 매개변수(s, sig)는 LINK_SESSION_SECRET에 의해 HMAC-SHA256 키가 지정됩니다. DB 행이 진실의 원천이며, HMAC은 SQLite에 접근하기 전에 잘못된 요청을 저렴하게 거부하는 역할을 합니다.
구성
모든 구성은 환경 변수(.env에서 로드)를 통해 이루어집니다.
변수 | 필수 | 기본값 | 설명 | ||
| 예 | — | Plaid 대시보드에서 확인 | ||
| 예 | — | Plaid 대시보드에서 확인. 이 서비스를 절대 떠나지 않음. | ||
| 아니오 |
|
|
|
|
| 아니오 |
| 고정된 API 버전 | ||
| 아니오 |
| 쉼표로 구분된 목록. 예: | ||
| 아니오 |
| ISO 국가 코드 쉼표 목록 | ||
| 아니오 |
| Plaid로 전송되는 안정적인 | ||
| 예 | — | 32바이트 16진수 ( | ||
| 예 | — | 32바이트 이상의 16진수. 서명된 링크 URL용 HMAC 키. | ||
| 아니오 |
| 링크 세션 수명 | ||
| 예 | — | 브라우저가 접속할 공개 HTTPS 기본 URL (예: | ||
| 아니오 |
| HTTP 포트. TLS는 상위(upstream)에서 종료됨. | ||
| 아니오 | — | 설정 시 | ||
| 아니오 |
|
|
| |
|
| — |
| ||
| 아니오 |
| SQLite 경로. 여기에 지속형 볼륨을 마운트하십시오. | ||
| 아니오 |
| Pino 로그 레벨. 모든 로그는 stderr로 출력됨. |
비밀 키 생성 방법:
make keys저장소
$DB_PATH에 SQLite (better-sqlite3) 사용. 두 개의 테이블이 중요합니다:
items—item_idPK, 암호화된access_token_blobBLOB, 기관 이름/ID, 상태, 동의 만료일.link_sessions— 단기 수명,expires_at이후 읽힐 때 및 60초 배경 스윕 중에 자동으로 만료됨.
액세스 토큰은 [1바이트 버전][12바이트 IV][16바이트 GCM 태그][N바이트 암호문]으로 저장됩니다. GCM 태그가 검증되지 않으면 복호화가 실패합니다.
보안 모델
MCP HTTP 전송은 모든 요청에
Authorization: Bearer $MCP_BEARER_TOKEN을 요구합니다. 없으면 에이전트 플릿이 모든 연결된 은행 계좌를 인터넷에 노출하게 됩니다.브라우저용
/link/*경로는 서명(HMAC)되어 있으며 DB 기반의 단기 세션에 바인딩됩니다.TLS는 상위(upstream)(nanoclaw / Caddy 등)에서 종료되는 것으로 간주합니다. 컨테이너는 내부적으로 일반 HTTP를 사용하므로 프록시를 통해서만 노출하십시오.
모든 Plaid 토큰은 저장 시 암호화됩니다. SQLite 파일을 탈취하더라도
PLAID_ENCRYPTION_KEY가 없으면 공격자는 토큰을 사용할 수 없습니다.MCP 도구는 에이전트에게 액세스 토큰을 절대 반환하지 않습니다. 불투명한
item_id/account_id문자열만 MCP 경계를 넘습니다.
로컬 개발
npm install
make setup # creates .env from env.example
make keys >> .env # append fresh PLAID_ENCRYPTION_KEY / LINK_SESSION_SECRET / MCP_BEARER_TOKEN
# edit .env: PLAID_CLIENT_ID, PLAID_SECRET, LINK_BASE_URL
npm run dev # tsx with hot reload로컬 링크 테스트를 위해서는 HTTPS 터널이 필요합니다(Plaid Link onSuccess는 http://localhost에서 작동하지 않음). cloudflared, ngrok 또는 실제 Caddy 리버스 프록시 모두 작동하며, 제공받은 공개 호스트 이름을 LINK_BASE_URL에 입력하십시오.
Docker
make build
make up
make logsCompose 파일은 ./data:/data를 마운트하여 SQLite DB가 재시작 후에도 유지되도록 합니다. nanoclaw 배포 시 해당 바인드 마운트를 클러스터 관리형 지속형 볼륨으로 교체하십시오.
호스팅된 인스턴스에 에이전트 연결
에이전트 컨테이너의 MCP 클라이언트 구성 내:
{
"mcpServers": {
"plaid": {
"url": "https://plaid-mcp.your-domain.example/mcp",
"headers": {
"Authorization": "Bearer <MCP_BEARER_TOKEN>"
}
}
}
}에이전트는 nanoclaw가 다른 에이전트 비밀 키에 사용하는 비밀 주입 메커니즘을 통해 Bearer 토큰을 얻습니다. PLAID_SECRET이나 액세스 토큰은 절대 볼 수 없습니다.
라이선스
내부용.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Personal finance for AI agents — onboard, import statements, categorize & budget over MCP.
Read-only finance MCP server. Connects your banks, cards, payment apps, books and payroll into one ledger for your AI. Can't move money. Open source (AGPL-3.0), free during beta.
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Persistent memory for AI assistants — one shared, OAuth-secured vault for every MCP client.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceSelf-hosted MCP server enabling Claude to query bank accounts, balances, and transactions through Plaid with OAuth and TLS.-
- AlicenseNot gradedqualityDmaintenanceA local MCP server that provides read-only SQL access to financial accounts via Plaid, enabling natural language queries about transactions, balances, and holdings.MIT
- FlicenseAqualityDmaintenancePersonal finance MCP server that integrates Plaid bank data with local SQLite memory for conversational budgeting, goal tracking, and transaction management.15-
- AlicenseNot gradedqualityBmaintenanceMCP server that exposes banking data (connections, accounts, balances, transactions) and agent skills, allowing AI agents to query and refresh financial data via stdio.154 npm6Apache 2.0