🔧 MCP Toolkit

开箱即用的 MCP (Model Context Protocol) 工具集 — 为 AI Agent 提供搜索、文件、Shell 能力

Plug-and-play MCP tools for AI agents — Web Search, File Ops, Shell, and more.

🎯 为什么需要这个？

MCP 生态缺一套安全可控、开箱即用的工具集。mcp-toolkit 填补这个空白：

• 🚀 一行命令启动 MCP Server
• 🔍 内置 web_search、file_ops、shell 等高频工具
• 🔒 安全优先：默认只读、workspace 沙箱、命令白名单
• ⚡ 轻量依赖（核心仅需 Python 3.10+ + mcp 库）

📦 安装

pip install mcp-toolkit

🚀 快速开始

1. Web Search Server

mcp-toolkit search

在 Claude Desktop / Cline / Continue 中配置：

{
  "mcpServers": {
    "web-search": {
      "command": "mcp-toolkit",
      "args": ["search"]
    }
  }
}

Agent 可调用：

• web_search(query) — DuckDuckGo 搜索
• web_extract(url) — 提取网页内容（含 SSRF 防护）

2. File Operations Server

mcp-toolkit file --workspace ./my-project

提供工具：

• read_file(path) — 读取文件
• write_file(path, content) — 写入文件（需 --allow-write）
• list_dir(path) — 列出目录
• search_files(pattern) — 子串搜索文件内容

3. Shell Command Server

mcp-toolkit shell

提供工具：

• run_command(cmd, timeout) — 执行命令（白名单控制）
• get_env(key) — 读取环境变量（白名单控制）

4. 一键启动全部

mcp-toolkit all

🛠 内置工具

| 工具 | 描述 | 模块 | |------|------|------| | web_search | DuckDuckGo 搜索 | search | | web_extract | 提取网页文本（含 SSRF 防护） | search | | read_file | 读取文件内容 | file | | write_file | 写入文件（需 --allow-write） | file | | list_dir | 列出目录结构 | file | | search_files | 子串搜索文件内容 | file | | run_command | 执行 Shell 命令（白名单） | shell | | get_env | 读取环境变量（白名单） | shell |

🔒 Security

mcp-toolkit exposes real system access to AI agents. 安全设计：

🔐 权限矩阵

| 能力 | 默认状态 | 开启方式 | 风险等级 | |------|:--:|------|:--:| | 文件读取 | ✅ 开启 | 无需额外参数 | 🟢 低 | | 目录列表 | ✅ 开启 | 无需额外参数 | 🟢 低 | | 文件写入 | ❌ 关闭 | --allow-write | 🟡 中 | | 文件覆盖 | ❌ 关闭 | --allow-overwrite | 🟡 中 | | Shell 执行 | ❌ 关闭 | 白名单 only | 🔴 高 | | 网页搜索 | ✅ 开启 | 无需额外参数 | 🟢 低 | | 网页内容提取 | ✅ 开启 | 无需额外参数 | 🟡 中 | | 环境变量读取 | ✅ 白名单 | — | 🟡 中 | | 路径沙箱 | ✅ 强制 | — | 🛡️ 保护 | | SSRF 防护 | ✅ 内网 IP 拦截 | — | 🛡️ 保护 | | 大文件限制 | ✅ 10MB | — | 🛡️ 保护 |

⚡ 危险组合

以下组合在特定场景下风险较高：

| 组合 | 风险 | 建议 | |------|------|------| | --allow-write + Shell | Agent 可写入脚本后执行 | 只在隔离环境中同时开启 | | web_extract + --allow-write | 网页内容可注入本地文件 | 限制写入目录不在 PATH 中 | | Shell 白名单含 python/node | 等价于给 Agent 本地执行能力 | 仅在完全可信的 workspace 中使用 | | workspace 指向 $HOME 或 / | Agent 可操作所有个人文件 | 始终指向独立项目目录 | | all 模式 | 开启所有能力 | 不推荐新手使用，仅限完全隔离环境 |

🚀 推荐使用方式

# 最安全：只开文件读取 + 搜索
mcp-toolkit search          # 搜索 server
mcp-toolkit file --workspace ./project   # 只读文件 server

# 需要写文件时
mcp-toolkit file --workspace ./project --allow-write

# 需要 Shell 时（谨慎）
mcp-toolkit file --workspace ./project --allow-write --allow-shell

# ⚠️ 不推荐新手
mcp-toolkit all  # 所有能力全开，仅限沙箱环境

Never expose write or shell tools to untrusted prompts. 所有文件操作限定在 --workspace 内，路径逃逸被拦截。

📁 项目结构

mcp-toolkit/
├── mcp_toolkit/
│   ├── __init__.py
│   ├── cli.py          # 命令行入口
│   ├── search.py       # Web Search MCP Server + SSRF guard
│   ├── file_ops.py     # File Ops MCP Server + workspace sandbox
│   ├── shell.py        # Shell MCP Server + allowlist
│   └── workspace.py    # Path sandbox implementation
├── tests/
│   └── test_toolkit.py
├── README.md
├── LICENSE
└── pyproject.toml

🧩 Studiopig Agent Stack

MCP Toolkit 是 Studiopig Agent Stack 的一部分——一套面向中文开发者的轻量本地 AI Agent 基础设施：

• 📋 awesome-ai-agents-cn — 中文 Agent 选型入口
• 🔧 mcp-toolkit — 安全默认的本地 Agent 工具箱
• 🧠 agent-memory-lite — 本地 Agent 长期记忆层

三个项目互相独立，组合使用可覆盖本地 Agent 的发现→工具→记忆全链路。

🤝 贡献

欢迎 PR！特别需要：

• 🌏 更多搜索引擎后端（Baidu、Bing 等）
• 🔌 新 MCP Server（数据库、API 等）
• 📚 更多 Agent 框架配置示例

Build agents, not boilerplate.