🌤️ FastMCP Weather Server

🌤️ FastMCP 天气服务

使用 FastMCP 和 TypeScript 构建的生产级天气 MCP 服务，可与 Claude Desktop、VS Code 和 Cursor 无缝集成。

✨ 功能

• 🌍 实时天气数据 - 获取全球任意城市的当前天气
• 🔒 类型安全 - 使用 TypeScript 和 Zod 验证构建
• 📊 进度报告 - 内置天气请求进度跟踪
• 📝 结构化日志 - 提供全面的日志记录和上下文
• 🛠️ 轻松测试 - 内置用于开发和调试的 CLI 工具
• 🔌 通用集成 - 兼容 Claude Desktop、VS Code 和 Cursor
• ⚡ 快速开发 - 速度比传统 MCP SDK 快 5 倍

🚀 快速开始

先决条件

• Node.js 20.18.1 或更高版本（关键要求）
• OpenWeatherMap API 密钥（免费套餐：每天 1,000 次调用）

安装

git clone https://github.com/abhilashsahoo/fastmcp-weather-server.git
cd fastmcp-weather-server
npm install

设置

1. 获取 OpenWeatherMap API 密钥：

   • 在 openweathermap.org/api 注册
   • 从控制面板复制 API 密钥

2. 创建环境文件：

   cp .env.example .env
   

3. 将 API 密钥添加到 .env：

   OPENWEATHER_API_KEY=your_api_key_here
   

开发

测试 MCP 服务：

npm run dev

试用交互式 CLI：

get_weather {"city": "London"}

通过可视化界面调试：

npm run inspect

构建生产版本：

npm run build

🔧 MCP 客户端集成

Claude Desktop

1. 找到配置文件：

   • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows： %APPDATA%\Claude\claude_desktop_config.json

2. 添加此配置：

   {
     "mcpServers": {
       "weather": {
         "command": "npx",
         "args": ["tsx", "/absolute/path/to/fastmcp-weather-server/src/server.ts"],
         "env": {
           "OPENWEATHER_API_KEY": "your_actual_api_key_here"
         }
       }
     }
   }
   

3. 重启 Claude Desktop 并测试：

   What's the weather like in Tokyo?
   

VS Code

1. 安装 MCP 扩展
2. 创建 .vscode/settings.json：

   {
     "mcp.servers": {
       "weather": {
         "command": "npx",
         "args": ["tsx", "./src/server.ts"],
         "cwd": "${workspaceFolder}",
         "env": {
           "OPENWEATHER_API_KEY": "your_actual_api_key_here"
         }
       }
     }
   }
   

Cursor IDE

1. 创建 .cursor/mcp.json：

   {
     "servers": {
       "weather": {
         "command": "npx",
         "args": ["tsx", "./src/server.ts"],
         "env": {
           "OPENWEATHER_API_KEY": "your_actual_api_key_here"
         }
       }
     }
   }
   

📋 可用脚本

脚本	描述
npm run dev	启动带 CLI 的 FastMCP 开发服务器
npm run inspect	打开可视化调试界面
npm run test-direct	不通过 CLI 直接测试服务器
npm run build	将 TypeScript 编译为 JavaScript
npm start	运行编译后的服务器

🛠️ API 参考

工具

get_weather

获取全球任意城市的当前天气信息。

参数：

• city（字符串，必填）：城市名称（例如，“London”“New York”）

返回值：

• 格式化的天气数据，包含温度、天气状况、湿度和风速

示例：

{
  "city": "London"
}

响应：

🌤️ Weather in London:
🌡️ Temperature: 15°C (feels like 13°C)
☁️ Conditions: partly cloudy
💧 Humidity: 65%
💨 Wind Speed: 3.2 m/s

🐛 故障排除

常见问题

问题	解决方案
Node.js 版本错误	更新至 Node.js 20.18.1 或更高版本：winget upgrade OpenJS.NodeJS
找不到服务器	检查 MCP 客户端配置中的绝对路径
API 密钥错误	检查 .env 和 MCP 客户端 env 部分中的 API 密钥
模块解析错误	删除 node_modules 并运行 npm install
FastMCP CLI 问题	运行 npm run test-direct，在不使用 CLI 的情况下进行测试

Windows 专属说明

通过 PowerShell 更新 Node.js：

# Using Chocolatey
choco upgrade nodejs

# Using Winget
winget upgrade OpenJS.NodeJS

# Using nvm-windows
nvm install 20.18.1 && nvm use 20.18.1

测试步骤

1. 直接测试服务器： npm run test-direct
2. 使用 FastMCP CLI 测试： npm run dev
3. 使用可视化界面测试： npm run inspect
4. 使用 Claude Desktop 测试： 重启 Claude 并询问天气情况

📊 项目结构

fastmcp-weather-server/
├── src/
│   └── server.ts          # Main FastMCP server
├── dist/                  # Compiled JavaScript (generated)
├── .env                   # Environment variables (create from .env.example)
├── .env.example           # Environment template
├── .gitignore            # Git ignore rules
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md             # This file

🌟 功能详述

FastMCP 的优势

• 零配置： 通过单个构造函数设置服务器
• 内置测试： 包含 CLI 和 Web 界面
• 进度报告： 实时进度更新
• 结构化日志： 使用数据对象记录上下文日志
• 类型安全： Zod 架构验证
• 错误处理： 用户友好的错误消息

天气数据

• 实时更新： 来自 OpenWeatherMap 的当前天气状况
• 全球覆盖： 全球任意城市的天气
• 全面数据： 温度、湿度、风力和天气状况
• 速率限制： 每天 1,000 次免费请求

🚀 部署

开发

npm run dev  # Test with FastMCP CLI

生产

npm run build  # Compile TypeScript
npm start      # Run compiled server

环境变量

变量	描述	必需
OPENWEATHER_API_KEY	OpenWeatherMap API 密钥	是
NODE_ENV	环境（开发/生产）	否

📈 性能

• 请求数： 每天 1,000 次天气调用（免费套餐）
• 响应时间： 平均 < 500ms
• 内存使用量： < 50MB
• 客户端支持： Claude Desktop、VS Code、Cursor

🤝 贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/amazing-feature
3. 提交更改：git commit -m 'Add amazing feature'
4. 推送到分支：git push origin feature/amazing-feature
5. 创建 Pull Request

📝 许可证

本项目基于 MIT License 授权，详情请参阅 LICENSE 文件。

🙏 致谢

• FastMCP - 优秀的 MCP 框架
• OpenWeatherMap - 免费天气 API
• Model Context Protocol - MCP 规范

🔗 相关项目

• FastMCP - TypeScript MCP 框架
• FastMCP Boilerplate - 入门模板
• MCP Servers - 官方 MCP 服务

---

使用 FastMCP 和 TypeScript 构建 ❤️