MCP （模型上下文协议）终端工具开发核心：subprocess 全解析 + 安全实践指南

在 MCP 智能体开发中，终端工具是让 AI 能 “操作电脑” 的关键 —— 比如让 AI 帮你查文件列表、执行 ping 命令、跑个小脚本，都得靠subprocess这个 Python 模块。这篇文章会用最通俗的话，从实战模板到核心知识点，把 MCP 终端工具开发讲明白，哪怕你是刚学 Python 的新手也能看懂。

一、先上手：写一个能直接用的 MCP 终端工具（抄就能用）

先给一个完整的、能直接运行的 MCP 终端工具代码，我们后面再拆细节。这个工具的作用很简单：让 AI 调用它执行终端命令（比如ls -al），并返回执行结果。

python

运行

# 新手提示：先安装依赖，终端执行 pip install fastmcp
import subprocess
from typing import Annotated
from pydantic import Field
from mcp.server.fastmcp import FastMCP

# 1. 初始化MCP服务（理解成“创建一个工具容器”）
mcp = FastMCP(name="terminal_mcp_server")

# 2. 注册一个“执行终端命令”的工具
@mcp.tool(
    name="run_command_once_tool",  # 工具名，AI会认这个名字调用
    description="一次性执行终端命令并返回结果，比如ls -al、ping example.com"
)
def run_command_once_tool(
        # 定义工具的输入参数：命令字符串
        command: Annotated[
            str, 
            Field(description="要执行的终端命令", example="ls -al")
        ]
) -> str:
    """核心功能：调用系统命令并返回结果"""
    return run_command_once(command)

# 3. 命令执行的核心函数（真正干活的地方）
def run_command_once(command: str) -> str:
    """
    新手白话解释：
    启动一个子进程执行命令，把输出全部收集起来返回
    """
    # 启动命令进程：合并正常输出和错误输出，用字符串格式返回
    process = subprocess.Popen(
        command,
        shell=True,  # 先这么用，后面会讲为什么有风险
        stdout=subprocess.PIPE,  # 捕获命令的正常输出
        stderr=subprocess.STDOUT,  # 把错误输出也合并进来（避免漏信息）
        text=True  # 输出是文字，不是看不懂的字节
    )
    
    # 等命令执行完，获取输出结果
    output, _ = process.communicate()  # 这里会等命令跑完
    output = output.rstrip('\n')  # 去掉结尾多余的空行
    return output