tuskledger-mcp

Tusk Ledger를 위한 모델 컨텍스트 프로토콜(MCP) 서버. AI 어시스턴트가 로컬 개인 금융 데이터에 타입이 지정된 방식으로 접근할 수 있게 해주며, 데이터를 기기 외부로 전혀 전송하지 않습니다.

소개

노트북에서 로컬 모델 컨텍스트 프로토콜(Model Context Protocol) 서버로 실행되는 작은 파이썬 패키지입니다. AI 클라이언트 설정(Claude Desktop, Cursor, Cowork, Claude Code 등 MCP를 지원하는 모든 도구)에 추가하면, 어시스턴트가 다음과 같은 도구를 호출할 수 있습니다:

• list_accounts — 잔액 및 동기화 상태를 포함한 모든 연결된 계좌 목록

• query_transactions — 날짜, 계좌, 카테고리 등으로 필터링

• search_transactions — 가맹점 및 메모에 대한 퍼지 텍스트 검색

• get_spending_summary — 기간별 카테고리 합계

• get_top_merchants — 가장 많이 지출한 가맹점 확인

• get_recurring_subscriptions — 넷플릭스, 헬스장 등 구독 서비스 확인

• get_upcoming_bills — 향후 30일간의 청구서 및 잔액 추이

• get_net_worth — 현재 순자산 및 12개월 추이

• get_holdings — 모든 투자 포지션 확인

• get_investments_summary — 포트폴리오 요약 및 자산 배분

• get_retirement_projection — 저장된 시나리오에 대한 몬테카를로 요약

• run_sync — Plaid 데이터 가져오기 트리거

• list_stale_accounts — 데이터가 오래된 계좌 목록

이 서버는 http://127.0.0.1:8000에서 로컬 Tusk Ledger 백엔드와 통신합니다. 데이터는 인터넷을 거치지 않습니다. "MCP 클라우드" 같은 것은 존재하지 않으며, 이 모든 것은 사용자의 기기에서 실행되는 하나의 파이썬 프로세스가 같은 기기의 다른 파이썬 프로세스와 통신하는 방식입니다.

존재 이유

Tusk Ledger는 에이전트 보조 사용자를 위해 구축되었습니다. 5년 전에는 혼자서 할 수 없었던 일들을 Claude / Cursor / Cowork에게 요청할 수 있는 사용자를 위한 것입니다. MCP 서버는 이 목표를 달성하기 위한 가장 강력한 수단입니다. 어시스턴트가 React UI를 긁어오거나 데이터베이스 스키마를 추측할 필요 없이, 금융 데이터에 타입이 지정된 구조화된 방식으로 접근할 수 있게 됩니다.

설치 후 활용 예시:

• "지난 6개월간 Whole Foods에서 결제한 거래를 '쇼핑' 대신 '식료품'으로 분류해줘." → 어시스턴트가 거래를 조회하고, 사용자가 확인하면 규칙을 생성합니다.

• "지난 분기에 커피에 얼마를 썼지?" → UI 클릭 없이 3초 만에 확인.

• "오늘 아침 순자산이 떨어졌는데, 원인이 뭐야?" → 어시스턴트가 계좌, 잔액, 최근 거래를 가져와 진단합니다.

• "올해 HSA 한도를 다 채울 수 있을까?" → HSA 잔액 + 연간 누적 기여금 + IRS 한도를 읽어 차액을 반환합니다.

사전 요구 사항

• 실행 중인 Tusk Ledger 설치 (메인 앱)

• Python 3.10+

• MCP 지원 클라이언트 (Claude Desktop, Cursor, Cowork, Claude Code 등)

설치

옵션 A — uvx (권장; 영구 설치 없음)

uv (pip install uv)가 설치되어 있다면:

// In your MCP client's config
{
  "mcpServers": {
    "tuskledger": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/BradMorphsters/tuskledger-mcp", "tuskledger-mcp"]
    }
  }
}

uvx는 격리된 파이썬 환경을 처리하므로 전역 파이썬 환경을 오염시키지 않습니다. 서버는 첫 실행 시 가져와서 캐시됩니다.

옵션 B — GitHub에서 pip install

pip install git+https://github.com/BradMorphsters/tuskledger-mcp

그런 다음 MCP 클라이언트에 설치된 tuskledger-mcp 바이너리를 지정합니다:

{
  "mcpServers": {
    "tuskledger": {
      "command": "tuskledger-mcp"
    }
  }
}

(venv를 사용하는 경우 which tuskledger-mcp의 전체 경로를 사용하세요.)

옵션 C — 개발을 위한 클론

git clone https://github.com/BradMorphsters/tuskledger-mcp
cd tuskledger-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .

MCP 클라이언트 설정 파일 위치

설정을 편집한 후 클라이언트를 다시 시작하세요. 서버는 클라이언트가 시작될 때 부팅되고 종료될 때 함께 종료됩니다.

설정

두 가지 환경 변수를 사용할 수 있으며, 모두 선택 사항입니다:

예시:

{
  "mcpServers": {
    "tuskledger": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/BradMorphsters/tuskledger-mcp", "tuskledger-mcp"],
      "env": {
        "TUSKLEDGER_BASE_URL": "http://127.0.0.1:8000",
        "TUSKLEDGER_TIMEOUT_SECONDS": "30"
      }
    }
  }
}

인증

이 v0 버전은 Tusk Ledger 백엔드가 DEV_BYPASS_AUTH=true로 실행 중이라고 가정합니다(메인 저장소 README에 문서화된 일반적인 단일 기기 패턴). 인증을 활성화한 경우, MCP 서버 호출은 401 오류를 반환하며 어시스턴트 응답에서 오류를 확인할 수 있습니다.

인증 지원은 로드맵에 포함되어 있습니다. 그때까지 인증과 MCP를 모두 사용하려면 어시스턴트를 사용할 때만 DEV_BYPASS_AUTH=true로 백엔드를 실행하고, 완료 후 다시 되돌리세요.

이 서버가 의도적으로 수행하지 않는 작업

설계상 v0는 읽기 전용에 가깝습니다. 서버는 다음을 노출하지 않습니다:

• 계좌, 거래, 규칙 또는 목표 삭제

• 데이터베이스 스키마 수정 또는 마이그레이션 실행

• 인증 비활성화 또는 암호화 키 교체

• Plaid 액세스 토큰 접근

• 127.0.0.1 외부로 데이터 전송

이유: AI 어시스턴트는 데이터를 이해하고 안전한 작업(동기화, 쿼리)을 수행하는 데 도움을 주어야 하지만, 되돌릴 수 없는 변경 사항은 웹 UI에서 직접 확인하며 수행해야 합니다. 향후 버전에서 명시적인 확인 절차를 거쳐 구조화된 쓰기 도구(예: "규칙 생성")를 추가할 수 있지만, 기준은 엄격하게 유지될 것입니다.

문제 해결

Could not reach Tusk Ledger backend at http://127.0.0.1:8000 — Tusk Ledger 앱이 실행 중이지 않습니다. 메인 저장소에서 ./start.sh를 실행하세요.

401 Unauthorized — 인증이 켜져 있습니다. 위의 인증 섹션을 참조하세요. 현재는 DEV_BYPASS_AUTH=true로 실행하세요.

404 Not Found — 백엔드에 호출하려는 엔드포인트가 없습니다. 이전 버전의 Tusk Ledger를 사용 중일 가능성이 높습니다. 메인 앱을 업데이트하고 MCP 클라이언트를 다시 시작하세요.

어시스턴트에 도구가 나타나지 않음 — MCP 서버 부팅에 실패했습니다. 클라이언트의 MCP 서버 로그를 확인하세요(Claude Desktop에는 "View MCP server logs" 메뉴 항목이 있습니다). 일반적인 원인: 설정의 잘못된 경로, PATH에 파이썬이 없음, uvx가 설치되지 않음.

일반 상태 점검 — 메인 Tusk Ledger 저장소에서 ./tuskledger doctor를 실행하세요. 이는 전체 설치에 대한 표준 진단 도구입니다.

개발

git clone https://github.com/BradMorphsters/tuskledger-mcp
cd tuskledger-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e .
pip install pytest pytest-asyncio
pytest tests/ -v

테스트는 MCP 전송을 불러오지 않으며, 모의 클라이언트를 사용하여 디스패치 계층을 직접 테스트합니다. MCP 프로토콜 자체는 래퍼일 뿐입니다.

CI는 GitHub Actions를 통해 Python 3.10/3.11/3.12에서 동일한 테스트 모음을 실행합니다(.github/workflows/ci.yml 참조).

프로젝트 링크

• 메인 앱: https://github.com/BradMorphsters/tuskledger

• 프로젝트 사이트: https://www.tuskledger.com

• 외부 브라우징 에이전트용: https://www.tuskledger.com/llms.txt

• 이슈 / 토론: https://github.com/BradMorphsters/tuskledger-mcp/issues

• 라이선스: MIT