Expense MCP

다음 두 부분으로 구성된 오픈소스 지출 추적기:

1. 지출을 Postgres(Supabase)에 저장하는 FastMCP 서버.

2. MCP 호스트 역할을 하는 Expo Android 앱. 지출 내역을 말하거나 입력하면 Claude가 MCP 도구를 대신 호출합니다.

라이브 MCP 엔드포인트:

https://indirect-olive-catshark.fastmcp.app/mcp

저장소: github.com/sahaniaditya/expense-mcp

기능

• add_expense — 금액, 카테고리, 날짜, 선택적 설명 저장

• get_expenses — 날짜 범위 내 지출 목록 조회

• data://categories — 식료품, 교통, 교육, 엔터테인먼트, 건강, 기타

• Android 음성 입력(“식료품에 250을 썼어”)

• 원격 서버용 Horizon / FastMCP Cloud OAuth

• 독립형 APK를 빌드하는 GitHub Actions 워크플로

Related MCP server: Expense Tracker MCP

아키텍처

Android app (MCP host)
  → Claude (Anthropic API)
    → FastMCP Cloud / local MCP server
      → Supabase Postgres

휴대폰 앱은 데이터베이스와 직접 통신하지 않습니다. Claude가 호출할 도구를 결정하고, 앱은 MCP 서버를 대상으로 해당 도구를 실행합니다.

MCP 서버

요구 사항

• Python 3.14+

• uv

• Postgres 데이터베이스(Supabase도 가능)

데이터베이스

expenses 테이블을 생성하세요:

create table if not exists expenses (
  id uuid primary key,
  price integer not null,
  category text not null,
  date timestamptz not null,
  description text
);

환경 설정

.env.example을 .env로 복사하고 연결 문자열을 설정하세요:

SUPABASE_URL=postgresql://postgres:YOUR_PASSWORD@db.YOUR_PROJECT.supabase.co:5432/postgres

.env는 절대 커밋하지 마세요.

로컬 실행

uv sync
uv run python main.py

HTTP MCP 엔드포인트는 http://127.0.0.1:8000/mcp입니다.

Inspector:

uv run fastmcp dev inspector main.py

배포

이 저장소를 GitHub에 푸시한 다음, Prefect Horizon / FastMCP Cloud에 엔트리포인트 main.py:mcp로 프로젝트를 생성하세요. 배포 설정에서 SUPABASE_URL을 시크릿으로 추가하세요.

클라이언트는 다음에 연결합니다:

https://YOUR-PROJECT.fastmcp.app/mcp

Horizon 인증은 기본적으로 활성화되어 있습니다. Horizon API 키(fmcp_...)를 사용하거나 클라이언트에서 OAuth 로그인을 완료하세요.

Android 앱

소스 코드는 mobile/에 있습니다.

Expo Go로 사용해 보기(개발)

Play Store의 Expo Go는 SDK 54와 일치해야 합니다.

cd mobile
npm install
npx expo start

Metro를 실행하는 컴퓨터가 여전히 필요합니다. 휴대폰만으로 설치하려면 APK를 사용하세요.

앱 설정

1. 연결을 엽니다.

2. FastMCP Cloud URL을 확인하세요(호스팅된 서버용으로 이미 채워져 있음).

3. Anthropic API 키를 붙여넣으세요.

4. 로그인 및 연결을 탭하고 Horizon 로그인을 완료하세요(또는 fmcp_ API 키를 붙여넣기).

5. 말하기 또는 추가를 사용하세요.

앱은 세션을 저장하고 다음 실행 시 다시 연결합니다.

APK 빌드

GitHub Actions는 릴리스 APK(JS 번들 포함, Metro 불필요)를 생성합니다:

1. main 또는 apk-github-actions로 푸시하거나 Actions 탭에서 Android APK 워크플로를 실행하세요.

2. expense-mcp-apk 아티팩트를 다운로드하세요.

3. 압축을 풀고 app-release.apk를 설치하세요.

4. 이전 디버그 빌드를 먼저 제거하세요.

로컬 EAS(선택 사항, Expo 계정 필요):

cd mobile
npx eas-cli login
npx eas-cli build -p android --profile preview

프로젝트 구조

main.py              MCP tools and resource
connection.py        Supabase / Postgres connection
mobile/              Expo SDK 54 Android client
.github/workflows/   APK build

라이선스

MIT. LICENSE를 참조하세요.