Python MCP Toolkit Server

一个基于 Python 编写的可扩展 MCP 工具服务器，使用官方 MCP Python SDK 的 FastMCP 作为服务入口，内置常用工具，并支持通过插件模块继续扩展工具集。

功能特性

• web_search 联网搜索：只保留 Bing 和 Tavily；provider=auto 有 TAVILY_API_KEY 时优先使用 Tavily，否则使用 Bing；也可显式选择 provider=bing 或 provider=tavily
• file_operation 文件操作：在一个工具内完成列表、读取、查找、grep、写入、替换、复制、移动和删除
• agent 轻量任务状态工具：记录任务目标、步骤、进展和完成结果
• 插件式工具扩展，支持按模块加载自定义工具
• 支持 stdio、sse 和 streamable-http 三种 MCP 传输方式
• 支持 .env 自动加载、命令行参数覆盖和远程请求头授权
• 提供 /healthz 健康检查端点，便于远程部署验证
• 默认安全边界：文件访问限制在 MCP_WORKSPACE，写入、复制、移动和删除默认关闭

文档

• 详细使用与扩展手册
• 离线版构建与安装

安装

本项目按系统级 Python 运行和安装。Termux 中系统 Python 通常是 /data/data/com.termux/files/usr/bin/python。先确认 python 指向系统 Python，然后安装到该 Python 环境：

python -c "import sys; print(sys.executable)"
python -m pip install -e .

在 Termux 或 Android Python 环境中，如果 pydantic-core 等原生依赖从源码编译并出现 Text file busy，使用单线程 Cargo 构建重试：

CARGO_BUILD_JOBS=1 python -m pip install -e .

离线环境可直接使用 mcp-toolkit-server-offline-pip.tar.gz：

mkdir -p mcp-toolkit-server-offline-pip
tar -xzf mcp-toolkit-server-offline-pip.tar.gz -C mcp-toolkit-server-offline-pip
cd mcp-toolkit-server-offline-pip
./install.sh

也可以使用 wheelhouse 格式安装：

./install-wheelhouse-offline.sh mcp-toolkit-server==0.1.0

在 Termux 中，如果希望脚本自动检查 Python、离线安装 pip 包、提示填写运行环境变量并启动服务，可以使用：

./termux-install.sh

脚本会把输入的运行环境变量默认保存到 .termux-mcp.env，下次运行自动加载。只安装不运行时使用：

./termux-install.sh --no-run

完整流程见 离线版构建与安装。

配置

不要把真实 API Key 写入源码。启动前通过环境变量配置工作区；TAVILY_API_KEY 可选，未设置时 web_search 的自动模式会使用 Bing；显式使用 provider=tavily 时必须设置该变量：

export TAVILY_API_KEY='your-tavily-key'
export MCP_WORKSPACE=/data/data/com.termux/files/home/mcp

启动时会自动读取当前目录的 .env 文件；已有环境变量优先级更高，不会被 .env 覆盖。也可以通过 MCP_ENV_FILE=/path/to/.env 指定配置文件。

常用可选配置：

export MCP_ENV_FILE=.env
export MCP_SERVER_NAME=python-mcp-toolkit
export MCP_TRANSPORT=stdio
export MCP_HOST=127.0.0.1
export MCP_PORT=8000
export MCP_STATELESS_HTTP=true
export MCP_AUTH_TOKEN=
export MCP_AUTH_HEADER=X-MCP-Auth-Token
export MCP_ALLOW_WRITE=false
export MCP_MAX_FILE_BYTES=2097152
export MCP_REQUEST_TIMEOUT=20
export MCP_TOOLKIT_PLUGINS=examples.custom_tools

关键环境变量说明：

变量名	默认值	说明
TAVILY_API_KEY	空	Tavily API Key。为空时 provider=auto 使用 Bing；显式 provider=tavily 需要设置。
TAVILY_API_URL	https://api.tavily.com/search	Tavily 搜索接口地址。
MCP_ENV_FILE	.env	启动时自动读取的环境变量文件。设为空可禁用自动加载。
MCP_TRANSPORT	stdio	MCP 传输方式：stdio、sse 或 streamable-http。
MCP_HOST	127.0.0.1	HTTP/SSE 监听地址，远程访问通常设为 0.0.0.0。
MCP_PORT	8000	HTTP/SSE 监听端口。
MCP_STATELESS_HTTP	true	streamable-http 默认不要求客户端维护 mcp-session-id。设为 false 可切回有状态 session 模式。
MCP_WORKSPACE	.	file_operation 允许访问的工作区根目录。
MCP_AUTH_TOKEN	空	HTTP/SSE 请求头授权码。为空时不启用请求头鉴权。
MCP_AUTH_HEADER	X-MCP-Auth-Token	读取授权码的请求头名。设为 Authorization 时也支持 Bearer <token>。
MCP_ALLOW_WRITE	false	是否允许 file_operation 执行写入、替换、复制、移动和删除。
MCP_MAX_FILE_BYTES	2097152	单个可读取文件大小上限，默认 2 MiB。
MCP_REQUEST_TIMEOUT	20	HTTP 请求超时时间，单位秒。
MCP_TOOLKIT_PLUGINS	空	逗号分隔的插件模块列表。

启动

安装后运行：

mcp-toolkit

也可以通过系统 Python 模块入口启动：

python -m mcp_toolkit.server

命令行参数会覆盖环境变量，常用示例：

mcp-toolkit \
  --transport streamable-http \
  --host 0.0.0.0 \
  --port 8000 \
  --workspace /data/data/com.termux/files/home/mcp

查看当前解析后的非敏感配置：

mcp-toolkit --show-config

常用命令行参数：

参数	说明
--env-file PATH	指定启动时读取的 .env 文件。
`--transport stdio	sse
--host HOST	覆盖 HTTP/SSE 监听地址。
--port PORT	覆盖 HTTP/SSE 监听端口。
--workspace PATH	覆盖 MCP_WORKSPACE。
--auth-token TOKEN	设置 HTTP/SSE 请求头授权码。
--auth-header NAME	设置读取授权码的请求头名。
--stateless-http / --stateful-http	覆盖 streamable-http 是否要求客户端维护 MCP session header。
--plugin MODULE	加载插件模块，可重复使用，也可逗号分隔。
--allow-write / --disable-write	覆盖 file_operation 写入、复制、移动和删除开关。
--show-config	打印非敏感配置后退出。

远程运行推荐使用 streamable-http。默认不需要请求头 token，也不要求客户端手动维护 mcp-session-id：

export MCP_TRANSPORT=streamable-http
export MCP_HOST=0.0.0.0
export MCP_PORT=8000
mcp-toolkit

远程地址：

http://服务器IP:8000/mcp

如需启用请求头鉴权，再额外设置：

export MCP_AUTH_TOKEN='change-this-token'

客户端请求需要带上：

X-MCP-Auth-Token: change-this-token

健康检查地址：

http://服务器IP:8000/healthz

启用 MCP_AUTH_TOKEN 后，健康检查同样需要带授权请求头。

MCP 客户端配置示例

{
  "mcpServers": {
    "python-mcp-toolkit": {
      "command": "/data/data/com.termux/files/usr/bin/python",
      "args": ["-m", "mcp_toolkit.server"],
      "env": {
        "TAVILY_API_KEY": "your-tavily-key",
        "MCP_WORKSPACE": "/data/data/com.termux/files/home/mcp",
        "MCP_ALLOW_WRITE": "false"
      }
    }
  }
}

示例中的 command 使用 Termux 系统 Python 路径；其他系统请替换为对应的系统 Python 可执行文件。插件模块需要能被系统 Python 导入；推荐把插件作为包安装到系统 Python，或从插件父目录启动客户端。

远程 streamable-http 客户端示例：

{
  "mcpServers": {
    "python-mcp-toolkit-remote": {
      "type": "streamable-http",
      "url": "http://服务器IP:8000/mcp"
    }
  }
}

内置工具

工具名	说明
web_search	联网搜索公开网页，只保留 Bing 和 Tavily；provider=auto 优先使用 Tavily，未配置 Key 时使用 Bing；可显式选择 provider=bing 或 provider=tavily，Bing 搜索最多返回 50 条并会自动翻页。
file_operation	在 MCP_WORKSPACE 内执行文件操作；写入、替换、复制、移动、删除需要 MCP_ALLOW_WRITE=true。
agent	管理轻量 agent 任务状态，记录目标、步骤、进展和完成结果。

扩展工具

新增工具推荐使用插件模块。插件需要暴露 register(registry, settings) 函数：

from mcp_toolkit.core.config import Settings
from mcp_toolkit.core.registry import ToolRegistry


def register(registry: ToolRegistry, settings: Settings) -> None:
    @registry.tool()
    def echo(text: str) -> dict[str, str]:
        """Return the input text."""
        return {"text": text}

启用插件：

export MCP_TOOLKIT_PLUGINS=examples.custom_tools
mcp-toolkit

多个插件用英文逗号分隔：

export MCP_TOOLKIT_PLUGINS=examples.custom_tools,examples.math_tools,examples.workspace_stats

更多扩展示例见 examples/ 目录和 详细使用与扩展手册。

验证

编译检查：

python -m compileall src examples tests

运行单元测试：

python -m unittest discover -s tests

列出已注册工具：

python - <<'PY'
import asyncio
from mcp_toolkit.server import create_server


async def main():
    server = create_server()
    tools = await server.list_tools()
    for tool in tools:
        print(tool.name)


asyncio.run(main())
PY

验证插件加载：

MCP_TOOLKIT_PLUGINS=examples.custom_tools python - <<'PY'
import asyncio
from mcp_toolkit.server import create_server


async def main():
    server = create_server()
    tools = await server.list_tools()
    print(any(tool.name == "echo" for tool in tools))


asyncio.run(main())
PY

安全说明

• TAVILY_API_KEY 只应通过环境变量传入，不应提交到仓库。
• 远程 HTTP/SSE 模式建议设置 MCP_AUTH_TOKEN，并在公网环境前置 HTTPS 反向代理。
• file_operation 只能访问 MCP_WORKSPACE 内路径。
• 文件写入、替换、复制、移动和删除能力默认关闭，需要显式设置 MCP_ALLOW_WRITE=true。
• 建议为不同项目配置不同的 MCP_WORKSPACE。

授权协议

本项目基于 GNU General Public License v3.0 or later（GPL-3.0-or-later）授权发布，详见 LICENSE。