Copilot Money MCP 서버

로컬 Copilot Money 데이터를 사용하여 AI로 개인 재정을 조회하고 관리하세요

면책 조항

이 프로젝트는 독립적인 커뮤니티 주도 프로젝트이며, Copilot Money 또는 그 모회사와 어떠한 방식으로도 제휴, 보증 또는 관련되어 있지 않습니다. 이 도구는 로컬에 캐시된 데이터를 AI 기반으로 조회할 수 있도록 독립 개발자가 만들었습니다. "Copilot Money"는 해당 소유자의 상표입니다.

개요

AI 어시스턴트가 사용자의 Copilot Money 개인 재정 데이터에 액세스할 수 있도록 하는 MCP 서버입니다. Mac에 로컬로 캐시된 Firestore 데이터베이스(LevelDB + Protocol Buffers)에서 데이터를 읽습니다. 읽기 작업은 100% 로컬에서 수행되며 네트워크 요청이 전혀 없습니다. 선택적 쓰기 모드(--write를 통해 활성화)는 요청한 변경 사항을 Copilot Money 앱 자체가 사용하는 것과 동일한 Firebase/Firestore 백엔드로 직접 전송하며, 사용자의 자격 증명으로 인증되고 제3자 서비스를 거치지 않습니다.

지출, 투자, 예산, 목표 등을 아우르는 35개의 도구:

• 17개의 읽기 도구 — 거래, 계좌, 보유 자산, 잔액, 카테고리, 정기 결제, 예산, 목표, 투자 성과 등을 조회

• 18개의 쓰기 도구 (선택 사항) — 거래 변경 사항 통합, 태그 관리, 예산 생성, 정기 결제 항목 업데이트 및 재정 정리

기본적으로 읽기 전용입니다. 쓰기 도구를 사용하려면 서버를 --write 옵션으로 명시적으로 시작해야 합니다.

개인정보 보호 우선

당사는 사용자의 데이터를 수집, 저장하거나 이 프로젝트에서 운영하는 서버로 전송하지 않습니다. 당사는 어떠한 서버도 운영하지 않습니다. 자세한 내용은 개인정보 처리방침을 참조하십시오.

• 분석, 텔레메트리 또는 어떠한 형태의 추적도 없음

• 읽기 작업은 완전히 로컬에서 수행 — 네트워크 요청 없음

• 기본적으로 읽기 전용 (--write를 전달하지 않으면 쓰기 도구 비활성화)

• 선택적 쓰기 모드에서는 요청이 사용자의 기기에서 Copilot Money의 Firebase/Firestore 백엔드로 직접 전송되며, 사용자의 자격 증명을 사용함 — 제3자 서비스를 거치지 않음

• 오픈 소스 — 코드를 직접 검증 가능

빠른 시작

사전 요구 사항

• Node.js 18+ (Claude Desktop에 번들로 포함됨)

• Copilot Money (macOS App Store 버전)

• Claude Desktop, Cursor 또는 MCP 호환 클라이언트

Claude Desktop을 통한 설치

1. Releases에서 최신 .mcpb 번들을 다운로드합니다.

2. .mcpb 파일을 더블 클릭하여 Claude Desktop에 설치합니다.

3. Claude Desktop을 재시작합니다.

4. 재정에 관해 질문을 시작하세요!

npm을 통한 설치

npm install -g copilot-money-mcp

그런 다음 Claude Desktop 설정(~/Library/Application Support/Claude/claude_desktop_config.json)에 추가합니다:

{
  "mcpServers": {
    "copilot-money": {
      "command": "copilot-money-mcp"
    }
  }
}

Cursor를 위한 설치

1. 패키지를 전역으로 설치합니다:

   npm install -g copilot-money-mcp

2. Cursor 설정(Cmd + ,) > Features > MCP Servers를 엽니다.

3. 서버 설정을 추가합니다:

   {
     "mcpServers": {
       "copilot-money": {
         "command": "copilot-money-mcp"
       }
     }
   }

수행 가능한 작업

지출 분석

"지난달 외식에 얼마를 썼지?"

"지난 30일 동안의 모든 Amazon 구매 내역을 보여줘"

"올해 나의 상위 5개 지출 카테고리는 무엇이지?"

get_transactions, get_categories를 날짜 범위, 텍스트 검색 및 카테고리 필터와 함께 사용합니다.

계좌 개요

"모든 계좌를 합친 나의 순자산은 얼마지?"

"지난 6개월 동안의 당좌 예금 잔액을 월별로 보여줘"

"주의가 필요한 은행 연결은 무엇이지?"

get_accounts, get_balance_history, get_connection_status를 사용합니다.

투자 포트폴리오

"현재 나의 보유 자산과 총 수익률은 얼마지?"

"지난 1년간의 AAPL 가격 추이를 보여줘"

"이번 분기 나의 시간 가중 수익률(TWR)은 얼마지?"

get_holdings, get_investment_prices, get_securities, get_investment_performance, get_twr_returns를 사용합니다.

예산 및 목표

"이번 달 예산에 맞춰 잘 지출하고 있나?"

"비상금 목표는 어떻게 진행되고 있지?"

"지난 6개월간의 목표 달성 기록을 보여줘"

get_budgets, get_goals, get_goal_history를 사용합니다.

구독 및 정기 결제

"내가 구독 중인 서비스는 무엇이지?"

"매달 정기 결제에 얼마를 지출하지?"

Uses get_recurring_transactions를 사용합니다.

재정 정리 (쓰기 모드)

"모든 Uber 거래를 교통비로 분류해줘"

"휴가 지출에 #vacation 태그를 달아줘"

"500달러짜리 월간 외식 예산을 만들어줘"

"Netflix를 월간 정기 결제로 설정해줘"

update_transaction, create_budget, update_recurring 등의 쓰기 도구를 사용합니다. --write 플래그가 필요합니다.

사용 가능한 도구

읽기 도구 (17)

쓰기 도구 (18) — --write 플래그 필요

쓰기 모드

기본적으로 서버는 읽기 전용 모드로 시작합니다. 쓰기 도구를 활성화하려면 --write 플래그를 사용하여 서버를 시작하십시오:

{
  "mcpServers": {
    "copilot-money": {
      "command": "copilot-money-mcp",
      "args": ["--write"]
    }
  }
}

쓰기 도구는 인증된 요청을 Copilot Money의 Firebase/Firestore 백엔드(Copilot Money 앱이 사용하는 것과 동일한 백엔드)로 직접 전송하여 Copilot Money 데이터를 수정하므로 변경 사항이 계정에 즉시 반영됩니다. 쓰기 작업은 로컬 Copilot Money 세션에서 추출된 Firebase 새로 고침 토큰을 사용하여 인증됩니다. 사용자의 자격 증명은 Google의 Firebase/Firestore 엔드포인트에 대한 인증된 요청 외에는 기기를 떠나지 않습니다. 제3자 서비스는 관여하지 않습니다. 자세한 내용은 PRIVACY.md를 참조하십시오.

설정

캐시 TTL

서버는 데이터를 메모리에 5분 동안 캐시합니다. 환경 변수를 통해 설정하십시오:

# Set cache TTL to 10 minutes
COPILOT_CACHE_TTL_MINUTES=10 copilot-money-mcp

# Disable caching (always reload from disk)
COPILOT_CACHE_TTL_MINUTES=0 copilot-money-mcp

refresh_database 도구를 사용하여 수동으로 새로 고칠 수도 있습니다.

디코드 타임아웃

대규모 데이터베이스(500MB 이상)의 경우 디코드 타임아웃을 늘리십시오(기본값: 90초):

# Via environment variable
DECODE_TIMEOUT_MS=600000 copilot-money-mcp

# Via CLI flag
copilot-money-mcp --timeout 600000

1GB가 넘는 데이터베이스의 경우 Node.js 메모리도 늘리십시오:

{
  "mcpServers": {
    "copilot-money": {
      "command": "node",
      "args": [
        "--max-old-space-size=4096",
        "/path/to/copilot-money-mcp/dist/cli.js",
        "--timeout", "600000"
      ]
    }
  }
}

지원되는 날짜 기간

period 매개변수는 다음 단축키를 지원합니다:

this_month last_month last_7_days last_30_days last_90_days ytd this_year last_year

알려진 제한 사항

로컬 캐시 의존성

이 서버는 클라우드가 아닌 Copilot Money의 로컬 Firestore 캐시에서 읽습니다. Firestore의 오프라인 지속성은 앱이 가져온 모든 문서를 캐시하므로, 로컬 데이터베이스에는 일반적으로 앱에서 본 모든 거래, 계좌, 예산, 목표 및 기타 데이터가 포함되어 있습니다. 기본 Firestore 캐시 크기는 100MB(수만 건의 거래를 처리하기에 충분함)이며, 이전 문서는 해당 제한을 초과하는 경우에만 LRU 가비지 컬렉션을 통해 제거됩니다.

캐시된 데이터를 최대화하려면: Copilot Money 앱을 열고 데이터(거래 내역, 계좌, 예산)를 탐색하여 로컬에 가져오고 캐시되었는지 확인하십시오.

문제 해결

데이터베이스를 찾을 수 없음

"Database not available"이 표시되는 경우:

1. Copilot Money가 설치되어 있고 데이터가 동기화되었는지 확인하십시오.

2. 데이터베이스 위치를 확인하십시오: ~/Library/Containers/com.copilot.production/Data/Library/Application Support/firestore/__FIRAPP_DEFAULT/copilot-production-22904/main

3. 디렉토리에 .ldb 파일이 있는지 확인하십시오.

4. 사용자 지정 경로를 제공하십시오: copilot-money-mcp --db-path /path/to/database

디코드 작업 시간 초과

"Decode worker timed out"이 표시되는 경우:

1. 타임아웃을 늘리십시오: copilot-money-mcp --timeout 300000 (5분)

2. 1GB 이상의 데이터베이스의 경우 Node.js 메모리도 늘리십시오: node --max-old-space-size=4096 dist/cli.js --timeout 300000

거래 내역을 찾을 수 없음

• Copilot Money 앱을 열고 동기화될 때까지 기다리십시오.

• 데이터베이스 구조가 변경되었을 수 있습니다 — 이슈를 여십시오.

기여

개발 설정, 아키텍처 및 새 도구 추가 방법에 대해서는 CONTRIBUTING.md를 참조하십시오.

라이선스

MIT 라이선스 - 자세한 내용은 LICENSE를 참조하십시오.

감사의 말

• Anthropic의 MCP SDK로 구축됨

• Zod을 사용한 데이터 유효성 검사

• Bun으로 개발됨