从零构建MCP工具：基于mcp-run实现AI可调用的天气查询脚本

1. 项目概述：从“AI调用工具”到“亲手造轮子”的转变

最近在折腾AI Agent和各类大模型应用时，我频繁地接触到“MCP”这个词。无论是Cursor里集成的各种MCP Server，还是Claude Desktop中琳琅满目的工具市场，MCP（Model Context Protocol）协议似乎正在成为连接大模型与外部工具、数据源的事实标准。但用着用着，我发现了一个痛点：市面上的MCP工具虽然多，但要么功能太“重”，要么不完全符合我某个特定的、细碎的工作流需求。比如，我就想快速查一下某个API的实时状态，或者把一段文本按照我自定义的规则格式化一下，为了这点事去配置一个完整的、复杂的MCP Server，感觉有点杀鸡用牛刀。

于是，我把目光投向了mcp-run。这个官方提供的轻量级工具，其核心设计理念就是让你能用最简单的方式——通常就是写一个脚本——快速创建一个一次性的、或临时的MCP工具，并直接暴露给AI使用。这简直完美契合了我“快速验证想法”、“解决特定小问题”的需求。但当我真正开始动手时，发现关于如何从零编写一个mcp-run可用的工具，中文社区的实践分享并不多，大多停留在概念介绍。所以，我决定结合自己踩坑和实现的过程，写一篇详细的指南，聊聊如何用mcp-run编写一个真正简单、可用的MCP工具。这不仅仅是调用AI，而是让AI能调用“你亲手打造”的工具，这种控制感和灵活性，是单纯使用现成工具无法比拟的。

2. MCP与mcp-run核心概念快速解析

在动手之前，我们得先统一一下认知，理解我们到底在做什么。这能帮你避开很多后续的迷惑。

2.1 MCP协议：AI的“手和脚”

你可以把大模型（LLM）想象成一个超级聪明但“瘫痪”在床的大脑。它知识渊博，逻辑缜密，但它没有手去操作电脑，没有眼睛去浏览网页，没有耳朵去听实时信息。MCP协议，就是为这个“大脑”安装的一套标准化的“神经接口”和“外骨骼”。

这套协议定义了一套清晰的通信规范：

1. 工具（Tools）：大脑可以发出的指令。比如“伸手拿水杯”、“睁开眼睛看网页”。在MCP里，一个工具对应一个可供AI调用的函数，有明确的名称、描述和参数格式。
2. 资源（Resources）：大脑可以读取的信息。比如“眼前的书桌上有哪些物品”、“当前的天气数据”。在MCP里，资源可以是文本、文件、数据库查询结果等，通过URI来标识和读取。
3. 提示（Prompts）：大脑可以调用的预设对话模板。比如“开始一次代码审查会话”。

MCP Server就是实现了这套协议的“外骨骼”本体。它暴露出具体的工具和资源，等待AI（MCP Client）来连接和调用。我们常说的“为Code添加MCP支持”，本质上就是让Code（作为Client）能够连接到这些Server，从而获得扩展能力。

2.2 mcp-run：你的“快速原型制造机”

而mcp-run，是MCP官方工具集里一个极其轻量的成员。它不是为了构建一个长期运行、功能完备的Server而生的。它的定位是“脚本运行器”。

它的工作模式非常直接：

1. 你写一个脚本（可以是Python、Node.js、Bash等任何能输出JSON到标准输出的程序）。
2. 这个脚本只需要做一件事：根据接收到的指令，执行对应的逻辑，然后把结果按照MCP约定的JSON格式打印出来。
3. mcp-run负责启动你的脚本，并扮演一个“翻译官”和“接线员”的角色。它把来自AI Client（如Claude Desktop）的请求，转换成对你的脚本的调用；再把你的脚本输出的JSON，转换成标准的MCP响应，传回给AI。

为什么选择mcp-run？

• 零框架依赖：你不需要引入任何复杂的MCP SDK或框架，一个能处理命令行参数和打印JSON的脚本足矣。
• 开发速度快：聚焦业务逻辑本身，无需关心Server的生命周期管理、长连接维护等复杂问题。
• 语言无绑定：可以用你最熟悉的脚本语言快速实现。
• 完美适配临时需求：为某个一次性数据分析、某个特定的文件处理任务快速创建一个AI助手工具，用完即弃，没有负担。

理解了这些，我们就可以开始动手了。我们的目标是：创建一个能查询指定城市当前天气的简单工具。

3. 开发环境准备与项目初始化

工欲善其事，必先利其器。我们先来把环境搭好。

3.1 基础环境配置

首先，确保你的系统已经安装了Node.js（mcp-run本身是一个Node.js工具）和Python（我们将用Python编写工具脚本）。在终端中检查：

node --version python3 --version

接下来，全局安装@modelcontextprotocol/sdk和mcp-run。虽然我们写工具脚本用不到SDK，但安装它通常能确保相关依赖齐全。

npm install -g @modelcontextprotocol/sdk

然后，通过npx直接运行mcp-run（推荐，无需全局安装）或者从源码构建。这里我们使用npx方式，因为它最干净。

# 尝试运行一下，查看帮助信息，这也会触发下载 npx @modelcontextprotocol/mcp-run --help

3.2 创建项目结构

创建一个干净的项目目录，这有助于管理我们的脚本和配置。

mkdir simple-weather-mcp cd simple-weather-mcp

在这个目录里，我们主要需要两个文件：

1. weather_tool.py：我们的Python工具脚本，包含核心逻辑。
2. server.py（可选但推荐）：一个极简的Python HTTP服务器脚本，用于模拟一个天气API。因为我们需要一个真实的数据源来演示，但又不希望依赖不稳定的外部网络API，所以自己模拟一个。

我们先创建server.py，用它来提供一个本地的、稳定的天气数据接口。

# server.py - 一个简单的模拟天气API服务器 from http.server import HTTPServer, BaseHTTPRequestHandler import json import sys # 模拟的天气数据 WEATHER_DATA = { "beijing": {"city": "北京", "condition": "晴朗", "temperature": 22, "humidity": 45}, "shanghai": {"city": "上海", "condition": "多云", "temperature": 25, "humidity": 70}, "shenzhen": {"city": "深圳", "condition": "阵雨", "temperature": 28, "humidity": 85}, "newyork": {"city": "纽约", "condition": "阴天", "temperature": 18, "humidity": 60}, } class SimpleWeatherHandler(BaseHTTPRequestHandler): def do_GET(self): # 从路径中提取城市名，例如 /weather/beijing parts = self.path.split('/') if len(parts) >= 3 and parts[1] == 'weather': city_key = parts[2].lower() weather = WEATHER_DATA.get(city_key) self.send_response(200 if weather else 404) self.send_header('Content-type', 'application/json') self.end_headers() if weather: response = json.dumps(weather).encode('utf-8') else: response = json.dumps({"error": "City not found"}).encode('utf-8') self.wfile.write(response) else: self.send_response(400) self.send_header('Content-type', 'application/json') self.end_headers() self.wfile.write(json.dumps({"error": "Invalid request path"}).encode('utf-8')) def log_message(self, format, *args): # 静默日志，避免干扰控制台输出 pass def run_server(port=8080): server_address = ('', port) httpd = HTTPServer(server_address, SimpleWeatherHandler) print(f"模拟天气API服务器已在 http://localhost:{port} 启动") print(f"支持的城市: {', '.join(WEATHER_DATA.keys())}") print("访问示例: GET /weather/beijing") try: httpd.serve_forever() except KeyboardInterrupt: print("\n服务器已关闭") httpd.server_close() if __name__ == '__main__': run_server()

打开一个新的终端窗口，运行这个服务器：

python3 server.py

保持这个终端运行，我们的天气API就在http://localhost:8080上待命了。

4. 核心工具脚本编写详解

现在，我们来编写核心的weather_tool.py。这个脚本必须遵循mcp-run的交互协议。

4.1 理解mcp-run的STDIN/STDOUT协议

mcp-run与你的脚本通过标准输入（STDIN）和标准输出（STDOUT）进行JSON通信。整个生命周期是这样的：

1. 初始化：mcp-run启动你的脚本，并向其STDIN发送一个初始化请求，表明MCP协议的版本等信息。你的脚本需要回复一个清单（list_tools的结果），告诉mcp-run“我提供了哪些工具”。
2. 空闲等待：脚本进入循环，从STDIN读取JSON行。
3. 调用工具：当AI想要使用某个工具时，mcp-run会向你的脚本发送一个call_tool请求，其中包含工具名和参数。
4. 执行并返回：你的脚本执行对应的逻辑，然后将结果以JSON格式打印到STDOUT。
5. 结束：当mcp-run退出时，你的脚本进程也会被终止。

我们的脚本需要处理两种请求：list_tools和call_tool。

4.2 编写weather_tool.py脚本

下面是完整的脚本代码，我会逐段解释。

#!/usr/bin/env python3 # weather_tool.py - 一个简单的MCP天气查询工具脚本 import sys import json import requests def list_tools(): """返回此脚本提供的工具清单""" tools = [ { "name": "get_current_weather", "description": "获取指定城市的当前天气情况。", "inputSchema": { "type": "object", "properties": { "city": { "type": "string", "description": "城市名称的英文拼音或小写字母（如：beijing, shanghai）" } }, "required": ["city"] } } ] return tools def call_tool(tool_name, arguments): """根据工具名和参数调用具体的工具""" if tool_name == "get_current_weather": city = arguments.get("city", "").strip().lower() if not city: return {"error": "参数 'city' 不能为空"} # 调用我们本地运行的模拟天气API try: # 注意：这里请求的是我们本地启动的 server.py response = requests.get(f"http://localhost:8080/weather/{city}", timeout=5) response.raise_for_status() # 如果状态码不是200，抛出异常 weather_data = response.json() # 格式化输出，使其对AI更友好 result_text = ( f"城市：{weather_data['city']}\n" f"天气状况：{weather_data['condition']}\n" f"温度：{weather_data['temperature']}°C\n" f"湿度：{weather_data['humidity']}%" ) return {"content": [{"type": "text", "text": result_text}]} except requests.exceptions.ConnectionError: return {"error": "无法连接到天气服务，请确保模拟服务器（server.py）已启动。"} except requests.exceptions.Timeout: return {"error": "请求天气服务超时。"} except requests.exceptions.HTTPError: return {"error": f"未找到城市 '{city}' 的天气信息。"} except Exception as e: return {"error": f"获取天气数据时发生未知错误：{str(e)}"} else: return {"error": f"未知工具：{tool_name}"} def main(): """主循环，处理来自mcp-run的JSON行请求""" # 首次启动，mcp-run会发送初始化请求，我们需要回复工具清单 for line in sys.stdin: if not line.strip(): continue try: request = json.loads(line) request_type = request.get("method") params = request.get("params", {}) if request_type == "initialize": # 回复初始化成功，并附上工具清单 result = { "jsonrpc": "2.0", "id": request.get("id"), "result": { "protocolVersion": "2024-11-05", "capabilities": { "tools": {} }, "serverInfo": { "name": "Simple Weather MCP Tool", "version": "0.1.0" } } } # 在初始化响应后，立即发送工具清单（这是一个单独的notification） tools = list_tools() print(json.dumps(result)) sys.stdout.flush() # 发送 tools/list 通知 print(json.dumps({ "jsonrpc": "2.0", "method": "tools/list", "params": {"tools": tools} })) sys.stdout.flush() elif request_type == "tools/call": # 调用工具 tool_call = params.get("toolCall") tool_name = tool_call.get("name") tool_args = tool_call.get("arguments", {}) call_result = call_tool(tool_name, tool_args) # 构建响应 response = { "jsonrpc": "2.0", "id": request.get("id"), "result": { "toolCalls": [ { "callId": tool_call.get("callId"), "result": call_result } ] } } print(json.dumps(response)) sys.stdout.flush() # 可以处理其他类型的请求，如 `resources/list`, `resources/read` 等 # 但本例中我们只实现工具相关功能 else: # 对于不支持的请求，返回方法未找到错误（可选） pass except json.JSONDecodeError: # 忽略无效的JSON输入 pass except Exception as e: # 捕获其他异常，避免脚本崩溃 error_response = { "jsonrpc": "2.0", "id": request.get("id") if 'request' in locals() else None, "error": { "code": -32000, "message": f"Server error: {str(e)}" } } print(json.dumps(error_response)) sys.stdout.flush() if __name__ == "__main__": main()

关键点解析：

1. 工具定义 (list_tools函数)：

   • 我们定义了一个名为get_current_weather的工具。
   • description字段至关重要，AI（如Claude）会根据这个描述来决定是否以及何时调用这个工具。描述要清晰、具体。
   • inputSchema定义了工具的参数。这里我们只要求一个city参数，并说明了其格式。required字段指明了这是必填参数。

2. 工具实现 (call_tool函数)：

   • 核心业务逻辑在这里。我们接收城市名，向本地模拟API发起请求。
   • 错误处理是重中之重。网络请求可能失败（连接错误、超时），API可能返回错误（HTTP 404），我们的脚本必须妥善处理这些情况，并返回结构化的错误信息，而不是崩溃或输出混乱的文本。这能保证AI和用户获得明确的反馈。
   • 返回格式必须遵循MCP对工具调用结果的约定：{"content": [{"type": "text", "text": "..."}]}。这是一个包含文本内容的数组。

3. 主循环协议处理 (main函数)：

   • 循环读取sys.stdin的每一行（每行是一个JSON-RPC请求）。
   • 初始化阶段：收到initialize请求后，除了回复协议版本等信息，必须紧接着发送一个tools/list通知，将工具清单告知客户端。这是很多初学者会漏掉的一步，导致工具列表为空。
   • 调用阶段：收到tools/call请求后，解析出工具名和参数，交给call_tool函数执行，然后将结果包装成JSON-RPC响应格式输出。
   • 输出后务必刷新缓冲区：sys.stdout.flush()确保数据立即发送出去，避免因缓冲导致通信延迟或超时。

5. 本地测试与调试技巧

脚本写好了，但在交给AI使用前，我们必须先进行充分的手动测试，确保协议通信和业务逻辑都正确。

5.1 模拟mcp-run进行手动测试

我们可以自己模拟mcp-run的行为，向脚本发送JSON请求来测试。创建一个test_script.py文件：

# test_script.py import subprocess import json import time # 启动我们的工具脚本进程 proc = subprocess.Popen( ['python3', 'weather_tool.py'], stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True, bufsize=1 # 行缓冲 ) def send_request(req): """发送一个JSON-RPC请求""" print(f">>> 发送: {json.dumps(req)}") proc.stdin.write(json.dumps(req) + '\n') proc.stdin.flush() def read_response(): """读取一行响应""" line = proc.stdout.readline() if line: print(f"<<< 接收: {line.strip()}") return json.loads(line) return None # 1. 发送初始化请求 init_request = { "jsonrpc": "2.0", "id": 1, "method": "initialize", "params": { "protocolVersion": "2024-11-05", "clientInfo": {"name": "TestClient"} } } send_request(init_request) # 等待并读取初始化响应和随后的tools/list通知 time.sleep(0.5) while True: try: resp = read_response() if resp and resp.get('method') == 'tools/list': print("工具清单已接收。") break except: break # 2. 发送工具调用请求 call_request = { "jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": { "toolCall": { "callId": "call_123", "name": "get_current_weather", "arguments": {"city": "beijing"} } } } send_request(call_request) # 读取调用结果 time.sleep(0.5) read_response() # 关闭进程 proc.terminate() proc.wait()

运行这个测试脚本：

python3 test_script.py

你应该能看到类似以下的输出，表明通信成功：

>>> 发送: {初始化请求...} <<< 接收: {初始化响应...} <<< 接收: {"jsonrpc": "2.0", "method": "tools/list", "params": {"tools": [...]}} 工具清单已接收。 >>> 发送: {调用请求...} <<< 接收: {调用结果...}

检查调用结果中是否包含了正确的北京天气信息。

5.2 集成到Claude Desktop进行真实测试

手动测试通过后，就可以进行终极测试了：让真正的AI来调用它。

1. 配置Claude Desktop： 找到Claude Desktop的配置文件。通常在以下位置：

   • macOS:~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows:%APPDATA%\Claude\claude_desktop_config.json
   • Linux:~/.config/Claude/claude_desktop_config.json

2. 编辑配置文件： 在配置文件中添加你的mcp-run工具配置。如果文件不存在，就创建它。

   { "mcpServers": { "simple-weather": { "command": "npx", "args": [ "@modelcontextprotocol/mcp-run", "python3", "/ABSOLUTE/PATH/TO/YOUR/simple-weather-mcp/weather_tool.py" ] } } }

   重要：必须使用python3命令的绝对路径，或者确保它在系统PATH中。weather_tool.py的路径也必须使用绝对路径。这是最常见的错误来源之一。

3. 重启Claude Desktop： 完全退出并重新启动Claude Desktop，使其加载新的配置。

4. 开始对话测试： 在新的对话中，直接询问：“Can you check the weather in Shanghai for me?” 或者 “请帮我查询一下上海的天气。” 如果一切配置正确，Claude应该会识别出可用的get_current_weather工具，并自动调用它。你会在Claude的回复中看到“正在调用工具...”的提示，然后显示出格式化后的天气信息。

6. 进阶优化与生产级考量

我们的基础工具已经能跑了，但要把它变得更强壮、更实用，还需要考虑以下几点。

6.1 增强脚本的健壮性

• 输入验证与清洗：我们的脚本只做了简单的strip().lower()。在生产环境中，需要对输入进行更严格的验证，防止注入攻击或非法输入导致脚本异常。例如，检查城市名是否只包含字母。
• 超时与重试机制：对于外部API调用，除了设置请求超时，还可以实现简单的重试逻辑（如重试2次），以提高在临时网络波动下的成功率。
• 资源管理与清理：如果工具涉及打开文件、数据库连接等，确保在脚本生命周期内或异常情况下能正确关闭和清理。
• 日志记录：将重要的操作和错误记录到文件，而不是仅仅打印到标准输出/错误流，便于后期排查问题。可以引入Python的logging模块。

6.2 扩展工具功能：从单一到多元

一个脚本可以提供多个工具。只需在list_tools函数中返回多个工具定义，并在call_tool函数中根据tool_name进行分发即可。

例如，我们可以增加一个工具：

def list_tools(): tools = [ { "name": "get_current_weather", "description": "获取指定城市的当前天气情况。", "inputSchema": {...} # 同上 }, { "name": "list_supported_cities", "description": "列出当前天气服务支持查询的所有城市。", "inputSchema": { # 这个工具不需要参数 "type": "object", "properties": {}, "required": [] } } ] return tools def call_tool(tool_name, arguments): if tool_name == "get_current_weather": # ... 原有逻辑 elif tool_name == "list_supported_cities": # 返回支持的城市列表 supported = ["北京 (beijing)", "上海 (shanghai)", "深圳 (shenzhen)", "纽约 (newyork)"] result_text = "当前支持查询的城市有：\n" + "\n".join(f"- {city}" for city in supported) return {"content": [{"type": "text", "text": result_text}]} else: return {"error": f"未知工具：{tool_name}"}

6.3 性能与部署思考

mcp-run模式的特点是每次调用都可能启动一个新的脚本进程。对于简单的、调用不频繁的工具，这没问题。但如果工具初始化成本高（如加载大模型、连接数据库），频繁启停会成为性能瓶颈。

此时，你有两个方向：

1. 升级为标准MCP Server：使用@modelcontextprotocol/sdk或其他语言的SDK，编写一个长期运行的Server。这样，昂贵的初始化只需一次。这是功能复杂、调用频繁的工具的最终归宿。
2. 在mcp-run脚本内做缓存：如果只是避免重复计算，可以在脚本内使用全局变量或轻量级缓存（注意进程隔离，mcp-run不同会话可能不是同一进程）。

部署上，如果你想让团队其他成员也能使用这个工具，你需要：

1. 将脚本和可能的配置文件打包。
2. 编写清晰的安装和配置说明（尤其是Claude Desktop配置那一步）。
3. 考虑使用Docker容器化，以确保运行环境一致。

7. 常见问题与排查实录

在这一路上，我踩过不少坑。这里把典型问题和解决方法列出来，希望能帮你节省时间。

问题现象	可能原因	排查步骤与解决方案
Claude Desktop完全看不到新工具	1. 配置文件路径错误。 2. 配置文件格式错误（JSON语法）。 3.mcp-run或脚本命令执行失败。	1.检查配置文件路径和名称：确保文件在正确位置，且名称是claude_desktop_config.json。 2.验证JSON格式：使用jq . your_config.json或在线JSON校验工具。 3.查看Claude Desktop日志：在Claude Desktop设置中打开“调试模式”或查看其输出日志（启动时在终端运行），里面通常会有MCP Server加载失败的具体错误信息。
Claude能看到工具，但调用时失败或超时	1. 脚本路径或解释器命令错误（相对路径问题）。 2. 脚本本身有Bug，启动后立即崩溃。 3. 脚本协议实现错误，未正确响应请求。	1.使用绝对路径：在配置文件的args中，为python3和脚本路径都使用绝对路径。 2.独立运行脚本：在终端直接运行python3 /path/to/your_tool.py，看是否有语法错误或导入错误。 3.进行手动STDIN测试：使用前面章节的test_script.py模拟调用，这是最有效的调试手段，能精准定位是协议问题还是业务逻辑问题。
脚本被调用，但返回“Internal server error”或AI收不到结果	1. 脚本没有输出合法的JSON-RPC响应。 2. 脚本输出后没有刷新缓冲区 (sys.stdout.flush())。 3. 脚本抛出了未捕获的异常。	1.检查输出格式：确保打印到stdout的每一行都是完整的、格式正确的JSON。可以用print(json.dumps(obj), flush=True)一步到位。 2.添加异常捕获：在main()函数最外层用try...except包裹，将任何异常都转换为JSON-RPC错误响应输出，避免脚本静默崩溃。 3.查看脚本的stderr：在Claude Desktop配置中，可以将stderr重定向到文件，查看运行时错误。
工具描述已更新，但Claude仍显示旧的	Claude Desktop可能缓存了工具列表。	1. 完全退出Claude Desktop并重新启动。 2. 如果还不行，尝试清除Claude Desktop的缓存数据（位置因系统而异，通常可在设置中找到或删除应用数据目录）。
调用工具时，AI说“参数不正确”	工具定义的inputSchema与AI传递的参数不匹配。	1. 检查list_tools返回的schema，确保required字段和properties定义正确。 2. 在call_tool函数开始处打印收到的arguments，确认AI传递的数据结构。有时AI可能会传递额外的参数或格式有细微差别。

一个关键的实操心得：始终先进行离线的、手动的协议测试。在集成到AI环境前，用test_script.py这样的模拟器验证你的脚本能正确响应initialize和tools/call请求。这能将问题隔离在最小的范围内，避免在Claude、Cursor等复杂环境中进行低效的黑盒调试。

编写mcp-run工具是一个“麻雀虽小，五脏俱全”的过程。它迫使你深入理解MCP协议最基本的通信单元，这种理解在你未来构建更复杂的标准MCP Server时，会是一笔宝贵的财富。从解决自己的一个小痛点开始，亲手造一个AI能用的工具，这种成就感远比单纯使用现成方案要大得多。当你看到AI流畅地调用着你写的代码，并给出答案时，你会感觉自己和AI的协作进入了一个新的层次——你不再是单纯的使用者，而是其能力的塑造者之一。