expense-tracker-mcp

개인 지출을 추적하기 위한 원격 MCP 서버로, Postgres를 기반으로 하며 두 가지 서로 다른 클라이언트가 사용하도록 설계되었습니다: 커넥터로서의 Claude, 그리고 커스텀 LangGraph 에이전트.

"오늘 식료품에 450을 썼어"라고 말해 지출을 기록한 다음, "이번 달 음식에 얼마를 썼지?"라고 물어보세요. 그러면 어느 클라이언트에서든 같은 답을 얻을 수 있습니다. 상태가 채팅 세션이 아닌 데이터베이스에 있기 때문입니다.

Claude (connector) ─┐
                    ├─► expense-tracker-mcp ─► Neon Postgres
LangGraph agent ────┘        (FastMCP)

상태

1단계는 실제 Neon 데이터베이스에 대해 종단 간 검증되었습니다. 배포가 다음 단계입니다.

Related MCP server: expense-tracker-mcp-server

도구

분류 체계는 리소스인 expenses://categories로도 게시됩니다. 그 중복은 의도적이며, Claude로 테스트하면서 알게 된 것입니다: 리소스는 읽기 전용 참조 데이터에 대한 올바른 MCP 프리미티브이지만, 클라이언트는 사용자가 첨부할 때만 리소스를 읽습니다. 모델에는 리소스가 아니라 도구가 주어집니다. "사용할 수 있는 카테고리는 무엇인가요?"라고 묻자, Claude는 분류 체계를 사용할 수 없다고 보고하고, 거부 오류에서 유효한 값을 읽을 수 있도록 쓰레기 행을 작성하겠다고 제안했습니다. 도구는 모델이 실제로 도달할 수 있는 것이며, 리소스는 리소스를 직접 탐색하는 클라이언트를 위해 남아 있습니다.

카테고리는 categories.json에 정의된 고정된 2단계 분류 체계입니다 — 20개의 카테고리로 구성되며, 각각 하위 카테고리를 가집니다. 이 범위를 벗어나는 모든 것은 유효한 값이 오류에 포함된 채로 거부되므로, 모델은 한 번의 왕복으로 스스로를 수정할 수 있습니다.

로컬에서 실행하기

사전 요구 사항: Python 3.10 이상, uv, Neon 계정(무료 티어로 충분합니다).

git clone https://github.com/<your-username>/expense-tracker-mcp
cd expense-tracker-mcp
uv sync

데이터베이스를 구성합니다. 예제 파일을 복사하고 Neon 연결 문자열을 입력하세요:

cp .env.example .env      # PowerShell: Copy-Item .env.example .env

그 문자열에서 중요한 두 가지가 있습니다:

• 풀링된 연결을 사용하세요 — 호스트에 -pooler가 포함되어 있습니다.

• ?sslmode=require&channel_binding=require 쿼리 문자열을 제거하세요. asyncpg는 libpq의 쿼리 매개변수를 허용하지 않으며 invalid dsn: invalid connection option "sslmode" 오류를 발생시킵니다. 대신 TLS는 코드에서 명시적으로 요청됩니다. (서버도 방어적으로 이를 제거하므로, 원본 문자열을 그대로 붙여넣어도 작동합니다.)

테이블을 생성합니다. schema.sql을 Neon SQL Editor 또는 모든 Postgres 클라이언트에서 한 번 실행하세요. 모든 문은 멱등적입니다.

서버를 시작합니다:

uv run python main.py            # http://127.0.0.1:8000/mcp

또는 MCP Inspector로 대화형으로 탐색해 보세요 (Node 필요):

uv run fastmcp dev inspector main.py

브라우저에서 /mcp에 대한 GET 요청은 406 Not Acceptable을 반환합니다. 이는 실패가 아니라 정상입니다 — MCP는 Accept: application/json, text/event-stream 헤더를 포함한 POST를 요구합니다.

배포

Prefect Horizon(이전 명칭: FastMCP Cloud)용으로 제작되었습니다. 엔트리포인트 main.py:mcp로 이 저장소를 가리키고 환경 변수에 DATABASE_URL을 설정하세요. 배포된 서버는 *.fastmcp.app URL을 받으며, 이를 Claude에 커넥터로 직접 추가할 수 있습니다.

의도적으로 .python-version 파일이 없습니다. Horizon은 virtualenv가 아닌 시스템 Python 접두사인 UV_PROJECT_ENVIRONMENT=/usr/local로 빌드합니다. 버전 고정이 있으면 uv가 이를 거부하고, 관리형 CPython을 다운로드한 다음, venv가 아닌 디렉터리를 재생성하려다 실패하게 됩니다. pyproject.toml의 requires-python = ">=3.10" 하한이면 충분합니다.

설계 결정

금액은 NUMERIC(12,2)이며 절대 float가 아닙니다. 이진 부동 소수점은 0.1을 정확히 표현할 수 없으므로, float 금액을 합산하면 오류가 누적되어 합계가 센트 단위로 어긋납니다. 금액은 Python에서 Decimal, Postgres에서 NUMERIC이며, 문자열로 전송됩니다 — JSON 숫자는 IEEE-754 배정밀도이므로, float로 직렬화하면 마지막 단계에서 어긋남이 다시 발생합니다. 450.55 + 120.45는 정확히 571.00을 반환합니다.

연결 풀은 지연 생성되며, import 시점에는 절대 생성되지 않습니다. import 시점에 연결하면 일시적인 데이터베이스 문제가 배포 실패로 바뀝니다. 지연 풀은 호출자가 재시도할 수 있는 도구 호출 실패 한 번으로 바꿉니다. 스키마 생성 역시 서버가 부팅 시 수행하는 것이 아니라 별도의 일회성 스크립트입니다.

모든 매개변수에 주석이 달려 있습니다. FastMCP는 타입 힌트에서 모델이 보는 JSON 스키마를 생성하므로, date: date는 {"type": "string", "format": "date"}로 모델에 전달되고 amount는 exclusiveMinimum: 0을 갖습니다. 타입이 없는 매개변수는 도구 호출 정확도를 눈에 띄게 저하시킵니다 — 또한 잘못된 입력은 도구 본문이 전혀 실행되기 전에 스키마 검증에서 거부됩니다.

모든 도구는 성공과 실패 모두에서 dict를 반환하며, ok 키를 포함합니다. 성공 시 리스트를, 오류 시 dict를 반환하는 도구는 모든 호출자가 결과를 사용하기 전에 타입 검사를 하도록 강제합니다.

user_id는 처음부터 존재하며, 기본값이 있고 현재는 사용되지 않습니다. 4단계에서는 모든 쿼리를 이 값으로 범위를 제한합니다. 나중에 데이터가 채워진 테이블에 NOT NULL 열을 추가하는 것은 마이그레이션입니다 — 지금 추가하는 것은 비용이 들지 않습니다. 의도적으로 도구 매개변수가 아닙니다: 모델이 user_id를 선택할 수 있다면, 어떤 클라이언트든 그냥 묻기만 해도 다른 사람의 지출을 읽을 수 있기 때문입니다.

로깅은 stderr로 출력됩니다. stdio 전송에서 stdout이 JSON-RPC 채널입니다, 잘못된 print() 하나가 프로토콜 스트림을 손상시킵니다.

아직 구현되지 않음

간과가 아니라 솔직한 한계입니다:

• 편집 또는 삭제 도구가 없습니다. 잘못 기록된 지출을 수정하려면 데이터베이스에 직접 접근해야 합니다. 실제로 불편함이 입증될 때까지 연기되었습니다.

• 통화 열이 없습니다. 모든 금액은 단일 통화로 가정됩니다.

• 인증이 없습니다. 모든 지출은 user_id = 'default'로 기록되므로, 배포된 서버는 4단계까지 단일 테넌트입니다.

구조

main.py           the server: three tools, one resource
schema.sql        one-time table + index creation
categories.json   the category taxonomy, single source of truth
.env.example      documents DATABASE_URL

사용된 기술

FastMCP 3 · asyncpg · Neon Postgres