Expense Tracker MCP Server

一个使用 FastMCP（v3.x）和 Python 构建的模型上下文协议（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 Desktop 中直接测试工具

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：交互式 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>

• 在浏览器中打开该链接，即可测试工具、查看 schemas，并实时查看请求/响应日志。

选项 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\<你的用户名>\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\\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.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.10 或未能正确升级。请通过 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