🔧 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 库）

Related MCP server: Sentinel Core Agent

📦 安装

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

🛠 内置工具

🔒 Security

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

🔐 权限矩阵

⚡ 危险组合

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

🚀 推荐使用方式

# 最安全：只开文件读取 + 搜索
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 框架配置示例