AI导哈

Shell接口MCP服务器

Simple shell-interface MCP Server (simple-mcp) 是一个基于Go语言的Model Context Protocol (MCP)服务器，用于将基本的Linux shell命令行接口到基于LLM的代理。

  • by vojtechpavlik
  • Go
  • 本地部署
  • 5 星标
  • 更新于
在 GitHub 查看 vojtechpavlik/simple-mcp

使用说明

简单外壳接口MCP服务器（简单MCP）

simple mcp是一个模型上下文协议（mcp）服务器设计的接口基础 基于LLM的代理的Linux shell命令行命令。它是使用Go和 这 mcp走 图书馆。

先决条件

  • 转到1.23+ （用于建筑）
  • mcphost （或另一个符合MCP的客户端）
  • 奥拉玛 （或其他LLM提供商）运行一个功能强大的模型 （例如qwen3编码器、llama3）。

建筑

要构建服务器和CLI二进制文件：

制造

这将产生 simple-mcp 和 simple-mcp-cli 二进制文件 当前目录。

命令行选项

  • -config <path>：YAML配置文件的路径 （默认值： ./simple-mcp.yaml).
  • -listen-addr <address>：要监听的网络地址和端口 （默认值： localhost:8080).服务器将公开多个标准MCP 端点： /mcp （多路复用）， /sse （专用苏格兰和南方能源公司），以及 /messages （专用流式HTTP）。
  • -tmpdir <path>：临时空间目录的路径。启用此功能 启用文件操作工具。
  • -verbose：启用MCP协议消息的详细日志记录。
  • -max-async-tasks <number>：要保留的异步任务的最大数量 内存（默认值：20）。
  • -transport <type>：MCP的运输方式。选项： auto （默认）， sse, http （流式HTTP），或 stdio.

配置

服务器通过以下方式配置 simple-mcp.yamlThe spec 部分支持 以下是全局选项：

  • listenAddr：与 -listen-addr.
  • tmpDir：与 -tmpdir.
  • verbose：与 -verbose.
  • maxAsyncTasks：与 -max-async-tasks.
  • transport：与 -transport.

这 spec 该节还定义了：

  • 资源： LLM可以读取的数据端点。
    • uri：资源的唯一标识符。
    • description：人类可读的描述。
    • content：静态文本内容。
    • contentFile：将加载其内容的文件的路径（相对于 配置文件）。
    • directory：将添加其整个文件子树的目录路径 作为个人资源。文件的相对路径将附加到 资源URI。
    • command：用于生成动态内容的shell命令。
    • intervalSeconds：建议客户端的刷新间隔。
  • 工具： 向LLM公开的可执行命令。
    • name：工具的名称。
    • description：这个工具做什么。
    • command：要运行的shell命令。如果路径指向可执行文件 文件（例如带有shebang的脚本），它直接执行。否则，它 作为shell命令执行(sh -c)与 set -o pipefail 由...启用 违约。支持Go模板语法（例如。， {{.paramName}}).
    • parameters：工具接受的参数名称列表。
    • envVars：从主机传递的环境变量名称列表。 注： 命令现在默认在干净的环境中运行；你必须 明确列出所需的任何主机环境变量。
    • ignoreExitCodes：要视为成功的返回代码列表。
    • async：如果为true，则该工具在后台运行并返回以下对象的任务URI 监测。
    • timeoutSeconds：命令的最长执行时间（默认值：30秒）。

使用LLM生成配置

您可以使用LLM为以下对象生成安全、加固的配置 simple-mcp. 这 llm-config-generation/ 目录包含 专门的系统提示和示例，可以将LLM转化为“安全” “架构师”为您的MCP设置。

请参阅 llm配置生成README 为了 详细说明。

参数验证

在执行之前，可以通过指定工具参数来验证工具参数 type 和/或a validator 正则表达式：

  • type:
    • path：有效的shell路径（没有未转义的空格或控制字符）。
    • directory：主机上的现有目录。
    • file：主机上的现有文件。
    • number：一个有效的数字。
    • integer：一个有效的整数。
    • word：不带空格的字母数字字符串。
    • filename：一个没有路径分隔符的有效文件名。
    • tmpDir：暂存空间中的现有目录。
    • tmpFile：暂存空间中的现有文件。
  • validator：参数值必须匹配的正则表达式。

例子：

  tools:
    - name: GetServiceLogs
      command: "journalctl -u {{.serviceName}} -n 10"
      parameters:
        - name: serviceName
          type: word
          validator: "^[a-z0-9.-]+$"

内置功能

  • 资源搜索： 服务器提供内置 SearchResources 工具 它允许LLM搜索所有资源URI、描述和 使用正则表达式的静态内容。
  • 异步任务： 标记为的工具 async: true 将在后台运行。 服务器提供 ListPendingTasks 和 TaskStatus 监控工具 这些工作。内存中的任务总数受到以下限制 maxAsyncTasks. 如果达到限制，启动新任务将驱逐最旧的已完成任务 或任务失败。如果所有插槽都充满了活动（挂起或正在运行） 任务，新的异步任务将失败，直到插槽可用。

刮擦空间

当 -tmpdir 旗帜或 tmpDir 设置配置选项， simple-mcp 为LLM提供了一组工具，用于操作其中的文件 目录。这包括创建、读取、删除和修改文件 （使用正则表达式搜索和替换），以及将资源复制到 刮擦空间。

CLI工具（简单的mcp-CLI）

提供命令行客户端用于测试和与服务器交互：

  • make inspect：启动交互式MCP检查器UI（需要Node.js/npx）。
  • simple-mcp-cli list-tools：列出所有可用工具。
  • simple-mcp-cli show-tool <name>：显示工具的描述。
  • simple-mcp-cli list-resources：列出所有可用资源。
  • simple-mcp-cli show-resource <uri>：显示资源的描述。
  • simple-mcp-cli resource <uri>：阅读资源的内容。
  • simple-mcp-cli tool <name> [--param value]...：调用带有参数的工具。

CLI选项

  • --server <address_or_url>：MCP服务器的地址或完整URL （默认值： localhost:8080).如果省略了路径， /mcp 使用。
  • --transport <type>：使用的运输方式(sse, http，或 stdio).
  • --command <arg>：为 stdio 传输，要运行的命令和参数。 可以多次指定。

例子

  • SSE（默认）： simple-mcp-cli --server localhost:8080 list-tools
  • 自定义路径： simple-mcp-cli --server http://localhost:8080/sse list-tools
  • 流式HTTP： simple-mcp-cli --transport http --server localhost:8080 list-tools
  • 音乐节目 ： simple-mcp-cli --transport stdio --command ./simple-mcp --command --transport --command stdio list-tools

安全和远程访问

重要提示： 此工具提供shell执行功能。不要暴露 此服务无需身份验证即可连接到公共互联网。

非根执行

强烈建议运行 simple-mcp 作为专用非root用户（例如。， simple-mcp).提供的 simple-mcp.service 配置为以此方式运行 用户，并使用Systemd的硬化功能来限制该过程的能力。

如果您的工具需要特定权限（如 iptables 或 dmesg)，你 应通过以下方式授予 AmbientCapabilities 在服务文件中，而不是 以root身份运行整个服务器。

限制网络访问

默认情况下，简单mcp绑定到localhost:8080，只允许本地连接。

模型上下文协议（MCP）本身不实现身份验证。如果你 需要在运行它的机器之外使用简单的mcp，这是 强烈建议使用 标准反向代理 （如Nginx、Apache等）， Caddy或Traefik）来处理：

  • TLS/SSL加密： 保护传输中的数据。
  • 身份验证： 限制授权用户的访问（例如，基本 Auth、OAuth2、OIDC）。

示例：带基本身份验证的Nginx

各种反向代理的综合示例可以在 webauth-examples/ 目录：

参数和壳体注射

simple-mcp 使用环境变量将参数传递给shell命令。 这可以防止直接命令注入（例如，传递 dummy; touch /tmp/evil 因为参数将不执行第二命令）。

但是，用户在设计工具命令时仍然必须小心：

  • 参数拆分和全局化： 默认情况下，如果您使用 {{.param}} 如果没有引号，shell将展开变量，然后执行word 分裂和球化。例如，如果 param 是 hello world, echo {{.param}} 成为 echo hello world （两个论点）。如果 param 是 *，它可能 展开到文件列表。
  • 使用双引号： 强烈建议在以下位置使用双引号 参数： "{{.param}}"。这确保了shell处理参数 作为一个单独的字符串，可以防止球形。
  • 输入验证： 虽然禁止直接执行，但参数 仍然传递给底层程序。确保这些程序处理不受信任的程序 输入安全，没有可能被触发的漏洞 恶意构建的参数（例如“Bobby Tables”场景）。
  • 避免 eval: 不要使用 eval 或具有参数的类似构造 在您的命令中，因为这将重新引入shell注入风险。

与mcphost一起使用

此存储库包含mcphost的示例配置。使用它

  1. 确保ollama正在运行，并且您拥有qwen3编码器：30b（或类似）型号 拉。
  2. 如果需要更改模型名称或提供者URL，请编辑mcphost.yaml。
  3. 运行mcphost：mcphost--配置mcphost.yaml

注： mcphost.yaml配置使用 相对路径。您必须从包含以下内容的目录运行mcphost systemprompt.txt（或更新yaml以提供完整路径），否则 mcphost将无法加载系统提示。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

相关 MCP