yagizhanakinci-taller/Local_MCP_Server

# Weather、Countries & Holidays MCP 服务器 一个本地 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 服务器，为任何 MCP 兼容的 AI 助手提供实时天气预报、国家概况和公共假日日历——所有内容均格式化为富文本 Markdown，包含表格、表情符号标识、ASCII 图表和可用于视觉渲染的月度网格。 ## 功能 该服务器暴露了四个 MCP 工具： | 工具 | 描述 | |---|---| | `get_weather` | 任意城市或地点的当前天气 + 7 天预报 | | `get_country_info` | 任意国家的人口、地理、语言、货币等详细信息 | | `get_location_overview | 合并天气与国家概况的单次格式化响应 | | `get_holidays | 任意国家与年份的完整公共假日日历，以月度网格呈现 | 原始数据从免费公共 API 获取，随后通过 OpenRouter LLM 转换为结构化 Markdown——包含表格、表情符号旗帜/天气图标、ASCII 图表和月度网格日历——以便 AI 助手渲染可视化内容而非输出纯 JSON。 **使用的 API（全部免费，除 OpenRouter 外无需密钥）：** - [Open-Meteo](https://open-meteo.com/) — 天气与地理编码 - [REST Countries](https://restcountries.com/) — 国家数据 - [Nager.Date](https://date.nager.at/) — 按国家与年份提供的公共假日 - [OpenRouter](https://openrouter.ai/) — LLM 格式化层（需要密钥） ## 先决条件 - Python 3.10+ - [OpenRouter API 密钥](https://openrouter.ai/keys) ## 安装 ``` git clone https://github.com/yagizhanakinci-taller/Local_MCP_Server.git cd Local_MCP_Server pip install -r requirements.txt cp .env.example .env # 打开 .env 并粘贴你的 OPENROUTER_API_KEY ``` ### `.env` 配置选项 ``` # 必需 OPENROUTER_API_KEY=sk-or-... # 可选 — OpenRouter 上的任何模型均可。默认值如下所示。 OPENROUTER_MODEL=anthropic/claude-opus-4.6-fast ``` 其他快速且廉价的选择： - `google/gemini-flash-1.5` - `mistralai/mistral-small` - `meta-llama/llama-3.1-8b-instruct:free` ## 连接至 Claude Desktop 无需服务器进程——Claude Desktop 会通过 stdio 直接启动脚本。 **1.** 打开 Claude Desktop → **设置** → **开发者** → **编辑配置** **2.** 在 `claude_desktop_config.json` 中添加以下代码块，将路径替换为你的实际 Python 可执行文件和 `server.py` 位置： ``` { "mcpServers": { "weather-countries-holidays": { "command": "C:\\Path\\to\\python.exe", "args": [ "C:\\Path\\to\\Local_MCP_Server\\server.py" ], "env": { "OPENROUTER_API_KEY": "sk-or-...", "OPENROUTER_MODEL": "anthropic/claude-opus-4.6-fast" } } } } ``` **3.** 保存文件并**重启 Claude Desktop**。 所有四个工具将自动在 Claude 界面中显示。 ## 连接至 ChatGPT、Cursor 或其他 HTTP 客户端 大多数非 Claude 客户端（ChatGPT、Cursor、Windsurf 等）通过 **HTTP** 而非 stdio 连接到 MCP 服务器。需要两项更改： ### 第一步 — 切换至 HTTP 传输 在 `server.py` 底部，将入口点从默认的 stdio 传输改为 `streamable-http`： ``` # 之前 — stdio，由 Claude Desktop 使用（当前默认） if __name__ == "__main__": mcp.run() # 之后 — HTTP，由 ChatGPT 和其他基于 Web 的客户端要求 if __name__ == "__main__": mcp.run(transport="streamable-http") ``` 然后启动服务器： ``` python server.py # 服务器现在监听于 http://localhost:8000 ``` ### 第二步 — 通过 HTTPS 暴露 8000 端口 ChatGPT 及大多数基于 Web 的客户端需要公网 **HTTPS** URL。使用以下工具将本地端口隧道化： **ngrok**（最常见）： ``` ngrok http 8000 # 给你一个类似这样的 URL：https://abc123.ngrok-free.app ``` **Cloudflare Tunnel：** ``` cloudflare tunnel --url http://localhost:8000 ``` **VS Code 端口转发**——在“端口”面板中，右键点击 8000 端口并设置可见性为 Public。 ### 第三步 — 在 ChatGPT 中添加服务器 URL 1. 进入 **ChatGPT** → **设置** → **连接器**（或计划中的 MCP 部分） 2. 添加一个新的连接器，指向你的 HTTPS 隧道 URL，例如： https://abc123.ngrok-free.app/mcp 3. 保存——所有四个工具将在你的对话中可用。 ## 项目结构 ``` Local_MCP_Server/ ├── server.py # MCP server — all tools and helpers ├── requirements.txt # Python dependencies ├── .env.example # Environment variable template ├── .env # Your local secrets (not committed) └── README.md ``` ## 故障排除 | 问题 | 解决方法 | |---|---| | `OPENROUTER_API_KEY 未设置` | 将密钥添加到 `.env` 或 Claude Desktop 的 `env` 块中 | | `Location not found` | 尝试更具体的名称，例如 `"London, UK"` 而非 `"London"` | | `get_holidays` 返回无数据 | 使用有效的 ISO 3166-1 alpha-2 国家代码，如 `"US"`、`"GB"`、`"BR"` | | ChatGPT 无法连接服务器 | 确保同时运行 `python server.py` 和 HTTPS 隧道 | | Claude Desktop 未显示工具 | 检查 JSON 配置文件中的路径/拼写错误，然后重启应用 | | `ModuleNotFoundError` | 使用正确的 Python 环境运行 `pip install -r requirements.txt` |

标签：AI助手集成, API集成, ASCII图表, Emoji图标, .env管理, LLM格式化, Markdown渲染, MCP服务器, Mutation, Nager.Date, Open-Meteo, OpenRouter, Python 3.10, Python后端, REST Countries, SEO: MCP工具, SEO: 天气国家节假日, SEO: 本地AI服务, 免费API, 可观测性, 可视化, 国家信息, 天气查询, 富文本展示, 提示注入, 月历网格, 本地服务器, 环境配置, 用户体验优化, 结构化数据, 节假日查询, 表格展示, 逆向工具, 集群管理