Expense Tracker MCP Server

FastMCP(v3.x)와 Python으로 구축된 Model Context Protocol(MCP) 서버로, 지출 추적을 위한 도구와 리소스를 MCP 호환 클라이언트(예: Claude Desktop, MCP Inspector)에 제공합니다.

📋 전제 사항

• 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: Demo 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 서버를 표준 I/O 모드로 실행하려면:

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\\hp\\AppData\\Local\\Python\\pythoncore-3.14-64\\Scripts\\uv.exe",
      "args": [
        "run",
        "--directory",
        "g:\\Projects\\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"..."

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 self node 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