AI导哈

FastMCP服务器

一个基于FastMCP的最小服务器，提供算术和骰子滚动工具，用于学习和测试MCP客户端连接。

  • by mayankchugh-learning
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 mayankchugh-learning/expense-mcp

使用说明

费用mcp

最低限度 FastMCP 提供算术和骰子掷骰子演示工具的服务器。使用它学习与Claude Desktop或其他MCP客户端的MCP接线。

需求

  • python 3.13+ （参见 .python-version / pyproject.toml)
  • 紫外线 用于环境和依赖关系管理

使用uv进行设置（逐步）

在尚未设置项目的机器上按顺序执行这些操作。

1.安装uv

选择 官方安装人员 对于您的操作系统。常见的单行线：

Windows（PowerShell）：

irm https://astral.sh/uv/install.ps1 | iex

macOS/Linux：

curl -LsSf https://astral.sh/uv/install.sh | sh

关闭并重新打开终端（或重新加载shell配置文件），以便 uv 在你的 PATH.

2.确认紫外线

uv --version

3.获取代码

克隆存储库并移动到其中（使用您的真实克隆URL或路径）：

git clone <repository-url> expense-mcp
cd expense-mcp

如果您已经解压缩了文件夹，只需 cd 到repo根目录（其中 pyproject.toml 生活）。

4.（可选）安装与uv匹配的Python

如果你没有Python 3.13可用，uv可以获取一个：

uv python install 3.13

回购 .python-version 针 3.13; uv sync 在创造环境时会尊重这一点。

5.创建虚拟环境并安装依赖项

从repo根目录：

uv sync

这将：

  • 创建 .venv 如果它丢失（或更新它以匹配锁文件）
  • 从以下位置安装软件包 pyproject.toml 使用以下版本 uv.lock

如果你想先自己创建venv（可选）：

uv venv --python 3.13
uv sync

6.（可选）激活虚拟环境

你做 不 如果您总是使用，则需要激活 uv run … （推荐）。要激活：

  • Windows（PowerShell）： .venv\Scripts\Activate.ps1
  • Windows（cmd）： .venv\Scripts\activate.bat
  • macOS/Linux： source .venv/bin/activate

7.验证安装

uv run fastmcp --version
uv run python --version

您应该看到FastMCP版本和Python 3.13.x。

快速参考（设置后）

目标 命令
从锁文件重新安装deps uv sync
添加新的依赖项 uv add <package>
刷新 uv.lock 编辑后 pyproject.toml uv lock
在项目环境中运行一次性命令 uv run <command>

运行服务器

开发/检查员 （适用于浏览器中的调试工具）：

uv run fastmcp dev inspector main.py

生产风格运行 （MCP客户端的stdio传输）：

uv run fastmcp run main.py

直接Python （stdio，与条目相同 if __name__ == "__main__"):

uv run python main.py

工具（API）

定义于 main.py:

工具 说明
roll_dice 卷材 n_dice 六面骰子；返回整数。
add_numbers a + b
subtract_numbers a - b
multiply_numbers a * b

每个函数的文档字符串是MCP客户端显示为工具描述的内容。

安装到Claude桌面

uv run fastmcp install claude-desktop main.py

然后：

  1. 重启 Claude Desktop完全退出（退出应用程序，而不仅仅是窗口）。
  2. 在设置中，确保 费用mcp （或类似名称）服务器是 启用.
  3. 如果安装命令出错（尤其是在Windows上），请参阅 Claude Desktop：配置路径/安装失败.

故障排除

当出现故障或行为异常时，请使用此部分。从与您的症状相匹配的每个小节的顶部开始。

uv和Python

症状 尝试什么
uv 无法识别 安装uv（请参阅 设置)那么 重新启动终端.确认操作系统的安装文档 uv 上 PATH.
uv sync Python运行失败或错误 uv python install 3.13那么 uv sync 再次从 回购根 （包含以下内容的文件夹 pyproject.toml).
似乎缺少包 来自repo根目录： uv sync.更喜欢 uv run <command> 所以这个项目 .venv 使用；避免混入全局 python 没有venv。
“没有 pyproject.toml“或错误的deps cd 到存储库根目录之前 uv sync / uv run.

Windows:PowerShell和脚本

症状 尝试什么
跑步 .venv\Scripts\Activate.ps1 失败（“运行脚本已禁用”） 仅适用于您的用户： Set-ExecutionPolicy -Scope CurrentUser RemoteSigned 在PowerShell中，然后重试。或使用 命令 和 .\venv\Scripts\activate.bat.
不需要激活 正在使用 uv run … 从repo根目录完全避免了激活。

服务器/开发检查器

症状 尝试什么
ModuleNotFoundError 或错误 fastmcp 跑步 uv run （例如。 uv run fastmcp dev inspector main.py)，不是全系统 python 它从未安装过deps。
检查器/dev命令错误 从以下位置运行 回购根；通行证 main.py 或者存在的路径。如果端口繁忙，请关闭其他检查器会话或参阅FastMCP文档以获取端口选项。
Stdio服务器立即退出 在终端中： uv run fastmcp run main.py 或 uv run python main.py 并阅读回溯。在再次连接Claude之前，请修复任何导入或配置错误。

Claude Desktop：MCP未连接或服务器错误

症状 尝试什么
服务器已禁用 设置→ MCP：转弯 上 费用mcp条目；重启克劳德。
错误的工作目录 MCP进程必须使用 cwd （或等效）设置为此回购 main.py 和 .venv 决心。重新运行 uv run fastmcp install claude-desktop main.py 或编辑 claude_desktop_config.json 因此，启动的命令的工作目录是项目根目录。
uv Claude启动时未找到 使用 完整路径 到 uv.exe 在配置中，或确保桌面应用程序看到的用户PATH包含uv（通常与您的交互式终端不同）。
JSON配置错误 打开 claude_desktop_config.json 在带有JSON验证的编辑器中。缺少一个逗号会破坏整个文件。

手动配置形状（说明性） --名称和密钥遵循您的Claude Desktop版本；调整路径：

"mcpServers": {
  "expense-mcp": {
    "command": "C:\\Users\\you\\AppData\\Local\\Programs\\uv\\uv.exe",
    "args": ["run", "fastmcp", "run", "main.py"],
    "cwd": "C:\\path\\to\\expense-mcp"
  }
}

在macOS/Linux上使用正斜杠和典型 uv 位置从 which uv.通过重新安装 fastmcp install 通常比手工编辑更容易。

Claude Desktop：配置路径或安装失败（Windows应用商店和路径）

经典路径（许多安装程序）： %APPDATA%\Claude （包含 claude_desktop_config.json).

Microsoft应用商店构建 经常使用：

%LOCALAPPDATA%\Packages\Claude_<id>\LocalCache\Roaming\Claude

如果 fastmcp install claude-desktop Claude没有配置文件夹或找不到它：

  1. 环境变量 --设置目录 实际上 持有 claude_desktop_config.json （名称取决于FastMCP版本）：

    • FASTMCP_CLAUDE_DESKTOP_CONFIG_DIR，或
    • CLAUDE_DESKTOP_CONFIG_DIR
      然后运行 uv run fastmcp install claude-desktop main.py 再次在同一终端会话中。

  2. 修补 .venv （高级） --修补 fastmcp\cli\install\claude_desktop.py 在...之下 .venv 可以教安装程序扫描 Packages\Claude_*\LocalCache\Roaming\Claude. 以后再说 uv sync 或者新鲜的静脉曲张会移除那个补丁 --重新应用或使用选项1或3。

  3. 目录连接 --如果 %APPDATA%\Claude 做 不 已作为真实文件夹存在，请将其连接到存储路径（调整 <your-id>；可能需要升高 命令):

    mklink /J "%APPDATA%\Claude" "%LOCALAPPDATA%\Packages\Claude_<your-id>\LocalCache\Roaming\Claude"

    然后运行 uv run fastmcp install claude-desktop main.py 再一次。

上游FastMCP可能会为门店布局添加一流的支持，因此不需要进行修补或连接。

助手无需使用工具即可回答

一个看起来正常的答案（例如“8+10=18”） 不 证明MCP运行。检查 工具使用 在UI中或强制使用一个独特的工具。

  1. 用户界面 --寻找工具/“使用过…”步骤，而不仅仅是最终信息。
  2. 清楚明白的命令 --例如“使用 add_numbers 8和10的费用mcp中的工具，并说明您使用了该工具。”
  3. 独特的工具 --例如“呼叫 roll_dice 和 n_dice=4匹配工具名称和模具结果意味着该服务器（除非另一个MCP定义了相同的工具名称）。
  4. 证明工具 --添加一个小工具 main.py 它返回一个只有该项目才会发出的字符串；调用一次并比较工具输出。

下的补丁或本地编辑 .venv 消失

一切只在内部发生了变化 .venv （包括手工修补的FastMCP文件） 替换 当你跑步时 uv sync，删除 .venv，或重新安装deps。比起长期的venv编辑，更喜欢环境变量、连接或有记录的配置；否则，每次同步后重新应用补丁。

项目布局

路径 角色
main.py FastMCP服务器和 @mcp.tool 定义
pyproject.toml 包元数据和依赖关系
uv.lock 锁定的依赖关系版本

相关 MCP