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: 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：交互式 Web UI（MCP Inspector）

要启动具有热重载功能的 MCP Inspector Web 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）

要以标准 I/O 模式运行 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 应用程序通常不会继承 shell 的 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. 检查 设置 > 开发者 以验证 expense-server 已连接。

🧰 可用工具（当前 main.py）

🔧 故障排除

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

在 FastMCP 3.x 中，fastmcp dev 是一个命令组。请使用 fastmcp dev inspector main.py 而不是 fastmcp dev 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