linux-mcp-server

Linux MCP Server

基于 Spring Boot 与 Spring AI 构建的 Model Context Protocol (MCP) 服务端，实现对本地与远程 Linux 主机的安全 Shell 命令执行。通过 MCP 标准接口，可被 Claude Desktop 等支持 MCP 的 AI 助手直接接入，扩展 AI 的运维能力。

目录

• 简介
• 功能亮点
• 快速开始
• 配置说明
• 与 AI 助手集成
• 安全建议
• 开发与调试
• 许可证

简介

Linux MCP Server 将 Shell 执行封装成一个 MCP 工具 executeShell，由 Spring AI 自动注册到 MCP Server。客户端通过标准 MCP 调用，指定目标主机和命令，即可在本地或远程 Linux 机器上执行脚本，返回标准输出与错误日志。

功能亮点

• 双模式执行：自动判断命令执行位置，支持本地进程调度与远程 SSH 执行。
• 连接池管理：基于 Caffeine 缓存复用 SSH 连接，默认 5 分钟自动过期清理。
• 轻量配置：使用简单的 hosts.json 维护远程主机清单，可热重启生效。
• Spring Boot 原生集成：开箱即用的 mvn spring-boot:run/可执行 JAR 部署方式，默认监听 3001 端口。
• MCP 协议兼容：依赖 spring-ai-starter-mcp-server-webmvc，支持 STREAMABLE HTTP 通道，适配主流 MCP 客户端。

快速开始

环境准备

• Java 17+
• Maven 3.6+（推荐使用仓库自带的 ./mvnw/mvnw.cmd）
• 具备 SSH 服务的目标 Linux 主机

获取代码

git clone <repository-url>
cd linux-mcp-server

配置远程主机

编辑 src/main/resources/hosts.json：

[
  {
    "ip": "192.168.1.100",
    "username": "devops",
    "password": "your_password"
  }
]

• ip：目标主机地址，需与 executeShell 中的 machineIp 对应。
• username/password：SSH 登录凭据，目前采用密码认证，可在代码中扩展密钥登录。

⚠️ 建议不要将生产凭据提交到版本库，使用环境变量或配置中心管理敏感信息。

启动服务

开发环境直接运行：

mvn spring-boot:run

或打包独立运行：

mvn clean package
java -jar target/linux-mcp-server-1.0.0.jar

启动完成后，默认在 http://localhost:3001/mcp 暴露 MCP 接入点。

配置说明

关键配置集中在 src/main/resources/application.yml：

server:
  port: 3001            # MCP Server 监听端口
spring.ai.mcp.server:
  name: linux-mcp-server
  version: 1.0.0
  protocol: STREAMABLE  # 使用流式 HTTP 传输
  streamable-http:
    mcp-endpoint: /mcp  # MCP 入口路径

如需自定义：

• 更改端口或 mcp-endpoint 时，记得同步更新 MCP 客户端配置。
• 若需要连接更多主机，直接在 hosts.json 中追加条目并重启服务。

与 AI 助手集成

以 Claude Desktop 为例，可在其 claude_desktop_config.json 中添加：

{
  "mcpServers": [
    {
      "name": "linux-mcp-server",
      "type": "http",
      "command": "http",
      "args": ["http://localhost:3001/mcp"]
    }
  ]
}

连接成功后，Claude 将自动发现工具 executeShell：

• machineIp（可选）：为空或本地地址执行本机命令。
• path（可选）：命令执行目录，缺省为 /。
• shell（必填）：需要执行的完整命令。

安全建议

• 凭据管理：hosts.json 以明文保存密码，仅用于开发或受控环境；生产环境请改用密钥认证或外部安全存储。
• 主机校验：当前使用 PromiscuousVerifier 跳过主机指纹校验，部署到生产前应替换为已知主机列表以防中间人攻击。
• 权限最小化：为远程机器创建受限用户，避免使用 root 账户并限制可执行命令范围。
• 网络限制：通过防火墙/安全组限制 MCP Server 与目标主机的访问来源。

开发与调试

• 代码结构主要位于 src/main/java/com/doodl6/mcp/linux，可按需扩展新的工具方法。
• 如需调整 SSH 缓存策略，可修改 RemoteShellService 中的 CACHE_DURATION_MINUTES、MAX_CACHE_SIZE。
• 修改完成后建议手动触发一次 executeShell（本地与远程各一次）验证输出与错误处理逻辑。

许可证

项目基于 MIT 许可证 开源，可自由使用与二次开发。