Expense Tracker MCP Server

Model Context Protocol (MCP) 서버로, FastMCP (v3.x)와 Python으로 구축되었으며, Claude Desktop 및 MCP Inspector와 같은 MCP 호환 클라이언트에 비용 추적을 위한 도구와 리소스를 제공하도록 설계되었습니다.

📋 사전 요구 사항

• Python: 3.10+ (Python 3.14로 테스트됨)

• uv: 빠른 Python 패키지 설치 및 해석 도구 (astral.sh/uv)

• Node.js: v22.x 또는 v24.x (LTS) — MCP Inspector UI에 필요

• Claude Desktop (선택 사항): Claude 내에서 직접 도구를 테스트하기 위한 용도

Related MCP server: Math Addition MCP Server

🚀 설정 및 설치

1. 프로젝트 및 환경 초기화

# Initialize uv project (if starting fresh)
uv init .

# Install FastMCP
uv add fastmcp

2. MCP Inspector UI를 위한 Node.js 준비

MCP Inspector(@modelcontextprotocol/inspector)는 Node.js v22.19.0+ 또는 v24+가 필요합니다. nvm-windows를 사용하는 경우:

nvm install lts
nvm use 24

Inspector를 전역으로 설치하거나 npx가 가져오도록 허용하세요:

npm install -g @modelcontextprotocol/inspector

🛠️ 실행 및 개발

옵션 A: 대화형 웹 UI (MCP Inspector)

핫 리로딩이 포함된 MCP Inspector 웹 UI를 시작하려면:

uv run fastmcp dev inspector main.py

• 이 터미널 창을 계속 열어 두세요.

• 콘솔에 인증 토큰이 포함된 로컬 URL이 출력됩니다:

  MCP Inspector Web is up and running at:
     http://127.0.0.1:6274?MCP_INSPECTOR_API_TOKEN=<token>

• 브라우저에서 해당 링크를 열어 도구를 테스트하고, 스키마를 검사하며, 실시간 요청/응답 로그를 확인하세요.

옵션 B: 서버 직접 실행 (STDIO)

MCP 서버를 표준 입출력 모드로 실행하려면:

uv run fastmcp run main.py

(또는 uv run python main.py)

🤖 Claude Desktop에 연결

1. 구성 파일 위치

Windows에서 Claude Desktop의 구성 파일은 다음 위치에 저장됩니다:

%APPDATA%\Claude\claude_desktop_config.json

(전체 경로: C:\Users\<YourUsername>\AppData\Roaming\Claude\claude_desktop_config.json)

2. 구성 설정

mcpServers 아래에 expense-server 정의를 추가하세요.

참고: Windows에서 Claude Desktop과 같은 GUI 애플리케이션은 셸 PATH를 상속하지 않는 경우가 많습니다. 항상 uv.exe의 절대 경로를 지정하세요.

{
  "mcpServers": {
    "expense-server": {
      "command": "C:\\Users\\pyash\\AppData\\Local\\Python\\pythoncore-3.14-64\\Scripts\\uv.exe",
      "args": [
        "run",
        "--directory",
        "d:\\expense-tracker-mcp-server",
        "fastmcp",
        "run",
        "main.py"
      ]
    }
  }
}

3. Claude Desktop 다시 시작

1. Claude Desktop을 완전히 종료하세요 (시계 근처의 Windows 시스템 트레이에서 종료되었는지 확인).

2. Claude Desktop을 다시 엽니다.

3. Settings > Developer에서 expense-server가 연결되었는지 확인하세요.

🧰 사용 가능한 도구 (현재 main.py)

🔧 문제 해결

1. Unknown command "main.py". Available commands: inspector, apps.

FastMCP 3.x에서 fastmcp dev는 명령 그룹입니다. fastmcp dev main.py 대신 fastmcp dev inspector main.py를 사용하세요.

2. node:util does not provide an export named 'styleText'

Node.js가 v20.12보다 오래되었습니다. nvm install lts && nvm use 24를 통해 Node v22+ 또는 v24+로 업데이트하세요.

3. Cannot find native binding (npm optional dependencies bug)

Node 버전 전환으로 인한 손상된 npx 캐시입니다. 다음을 실행하세요:

npm cache clean --force
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx" -ErrorAction SilentlyContinue
npm install -g @modelcontextprotocol/inspector