Personal Expense Tracker MCP

이 프로젝트가 하는 일

Personal Expense Tracker MCP는 개인 지출을 추적하는 간단한 로컬 MCP 서버입니다.

지출 데이터를 로컬 CSV 파일에 저장합니다.

서버는 MCP 클라이언트에 다섯 가지 특화된 도구를 제공합니다.

• 새 지출 추가

• 저장된 지출 목록 보기

• 지출 요약 만들기

• 기존 지출 수정

• 기존 지출 삭제

이 프로젝트는 간단하고 로컬에서 실행하기 쉽게 만들어졌습니다.

은행 계좌나 외부 API가 필요하지 않습니다.

Related MCP server: expense-mcp

요구사항

시작하기 전에 다음이 설치되어 있는지 확인하세요.

• Node.js 버전 20 이상

• npm

• Git

Node.js 확인

node --version

npm 확인

npm --version

Git 확인

git --version

설치

1 리포지토리 클론

git clone https://github.com/MohammadYousef-001/Personal-Expenses-Tracker.git

2 프로젝트 폴더로 이동

cd Personal-Expenses-Tracker

3 패키지 설치

npm install

npm이 필수 패키지 설치를 완료할 때까지 기다리세요.

데이터 파일

지출은 로컬에 다음 위치에 저장됩니다.

data/expenses.csv

CSV 파일은 다음 열을 사용합니다.

id,amount,category,date,description

열 이름을 변경하지 마세요.

MCP 서버 실행

서버를 시작하려면 다음을 실행하세요.

npm run dev

서버는 MCP 통신을 위해 표준 입력과 출력을 사용합니다.

로컬 서버이므로 웹 포트가 필요하지 않습니다.

MCP Inspector 실행

MCP Inspector는 도구를 수동으로 테스트하는 가장 쉬운 방법입니다.

다음을 실행하세요.

npm run inspect

MCP Inspector가 포함된 브라우저 창이 열립니다.

자동으로 열리지 않으면 터미널에 표시된 URL을 사용하세요.

Inspector에서

1. 서버에 연결

2. Tools 섹션 열기

3. 도구 선택

4. 입력값 입력

5. Execute Tool 클릭

6. 결과 확인

사용 가능한 도구

도구 1 add_expense

add_expense를 사용하여 새 지출을 저장하세요.

입력값

amount

지출한 금액입니다.

양수여야 합니다.

category

지출 카테고리입니다.

예시:

groceries
transport
bills
shopping

카테고리는 소문자로 저장되므로 카테고리 이름이 일관되게 유지됩니다.

date

지출 날짜입니다.

다음 형식을 사용해야 합니다.

YYYY-MM-DD

예시:

2026-08-12

날짜는 실제 달력에 존재하는 날짜여야 합니다.

다음은 유효하지 않습니다.

2026-99-99

description

지출에 대한 선택적인 간단한 정보입니다.

예시

{
  "amount": 25,
  "category": "groceries",
  "date": "2026-08-12",
  "description": "milk and bread"
}

요청이 성공하면 지출이 다음 파일에 추가됩니다.

data/expenses.csv

도구 2 list_expenses

list_expenses를 사용하여 저장된 지출을 확인하세요.

필터 없이:

{}

카테고리로 필터링:

{
  "category": "groceries"
}

월로 필터링:

{
  "month": "2026-08"
}

두 필터를 함께 사용:

{
  "month": "2026-08",
  "category": "groceries"
}

월은 다음 형식을 사용해야 합니다.

YYYY-MM

월은 01과 12 사이여야 합니다.

다음은 유효하지 않습니다.

2026-99

도구 3 get_spending_summary

get_spending_summary를 사용하여 지출 요약을 확인하세요.

예시:

{
  "month": "2026-08"
}

결과에는 다음이 포함될 수 있습니다.

• 선택한 월

• 총 지출 금액

• 지출 건수

• 카테고리별 총 지출

결과 예시:

month: 2026-08
total amount: 150
expense count: 4

category totals:
groceries: 80
transport: 30
bills: 40

실제 값은 data/expenses.csv 안의 데이터에 따라 달라집니다.

예시 프롬프트

지출 추가

I spent 25 on groceries today

이 프롬프트는 다음을 사용할 수 있습니다.

add_expense

지출 찾기

show my grocery expenses for this month

이 프롬프트는 다음을 사용할 수 있습니다.

list_expenses

지출 확인

how much did I spend this month

이 프롬프트는 다음을 사용할 수 있습니다.

get_spending_summary

입력 검증

프로젝트는 도구 입력값을 사용하기 전에 검증합니다.

잘못된 입력의 예시:

• 음수 금액

• 0 금액

• 잘못된 날짜 형식

• 실제 달력에 없는 날짜

• 유효하지 않은 월

• 너무 긴 카테고리

• 너무 긴 설명

잘못된 입력은 저장되기 전에 거부됩니다.

스키마 테스트

다음을 실행하세요.

npm run check:schema

성공하면 다음 결과가 표시되어야 합니다.

All expense schemas are valid.

문제 해결

문제 1 패키지가 없음

패키지 또는 모듈을 찾을 수 없다는 오류가 표시되면 다음을 실행하세요.

npm install

그런 다음 다시 시도하세요.

npm run dev

문제 2 MCP Inspector가 시작되지 않음

패키지가 설치되어 있는지 확인하세요.

npm install

그런 다음 다음을 실행하세요.

npm run inspect

이전 Inspector 프로세스가 계속 실행 중이면 다음을 누르세요.

Ctrl + C

그런 다음 Inspector를 다시 시작하세요.

문제 3 TypeScript 또는 스키마 오류

다음을 실행하세요.

npm run check:schema

모든 것이 올바르면 다음이 표시되어야 합니다.

All expense schemas are valid.

오류가 있으면 터미널에 표시된 파일 이름과 줄 번호를 확인하세요.

Inspector를 다시 시작하기 전에 오류를 수정하세요.

문제 4 잘못된 날짜

유효한 날짜는 다음 형식을 사용해야 합니다.

YYYY-MM-DD

유효한 예시:

2026-08-12

잘못된 예시:

2026-99-99

문제 5 지출이 반환되지 않음

다음을 확인하세요.

data/expenses.csv

CSV 헤더 아래에 지출 행이 포함되어 있어야 합니다.

파일에 헤더만 있으면 빈 결과가 정상입니다.

프로젝트 구조

중요한 프로젝트 파일:

Personal-Expenses-Tracker/
│
├── data/
│   └── expenses.csv
│
├── docs/
│   ├── design.md
│   └── threat-model.md
│
├── examples/
│
├── src/
│   ├── index.ts
│   ├── schemas/
│   ├── tools/
│   └── lib/
│
├── SECURITY.md
├── package.json
└── README.md

보안

도구 입력값은 신뢰할 수 없는 입력으로 취급됩니다.

프로젝트는 중요한 작업 전에 입력값을 검증합니다.

지출 파일 경로는 애플리케이션이 제어합니다.

MCP 클라이언트에 반환되는 오류는 짧게 유지됩니다.

더 자세한 오류는 디버깅을 위해 로컬 터미널에 남습니다.

지출 도구는 외부 네트워크 요청이 필요하지 않습니다.

더 많은 보안 정보는 다음에서 확인할 수 있습니다.

SECURITY.md

프로젝트 범위

이 프로젝트는 소규모 로컬 개인 지출 추적기입니다.

다음은 포함되지 않습니다.

• 은행 계좌 연결

• 자동 은행 거래 가져오기

• 사용자 로그인

• 클라우드 데이터베이스

• 완전한 그래픽 애플리케이션

• 재무 예측

주요 목표는 로컬 지출 추적을 위한 간단한 MCP 도구를 제공하는 것입니다.

라이선스

이 프로젝트는 MIT 라이선스를 사용합니다.

LICENSE를 참조하세요.