Skip to main content
Glama
linhanhan227

Python MCP Toolkit Server

by linhanhan227
OverviewSchemaSourceRelated ServersScoreDiscussionsAdmin
Python
Hybrid

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，写入、复制、移动和删除默认关闭

Related MCP server: MCP Server

文档

安装

本项目按系统级 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。

Available Tools

3 tools
agentC

管理一个轻量 agent 任务状态，用于记录目标、步骤、进展和完成结果。

ParametersJSON Schema
NameRequiredDescriptionDefault
actionNoagent 动作：start/status/update/finish/reset。status
taskNostart 时设置的任务目标。
stepsNostart 时设置的执行步骤；为空时使用默认执行步骤。
noteNoupdate/finish 时追加的进展、观察或结论。

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does not mention side effects (e.g., state mutation), authentication requirements, rate limits, or lifecycle behavior of actions (start, update, finish, reset). This is insufficient for a tool managing task state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, making it concise. It is front-loaded with the core purpose. However, it could be slightly more detailed without losing conciseness. Overall, it earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the moderate complexity (4 parameters, actions enum) and the presence of an output schema, the description is minimally adequate. It explains the high-level purpose but lacks details on action semantics, required states, and usage flow, making it incomplete for full guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so each parameter already has a description. The tool description adds no additional meaning beyond the schema. Baseline is 3, and the description does not compensate with extra context.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states the tool manages agent task status and records goals, steps, progress, and results. This is clear and distinguishes it from sibling tools (file_operation, web_search) which have different domains. However, the verb 'manage' is somewhat broad; a more specific verb like 'track' would improve clarity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description does not mention context, prerequisites, or exclusions. Sibling tools are quite different, but explicit when-to-use instructions are absent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

file_operationA

在 MCP_WORKSPACE 内执行文件操作；写入、复制、移动、删除需要 MCP_ALLOW_WRITE=true。

ParametersJSON Schema
NameRequiredDescriptionDefault
actionYes文件操作类型：list/info/read/read_lines/write/append/replace/mkdir/copy/move/delete/find/grep。
pathNoMCP_WORKSPACE 内的文件或目录路径。.
contentNowrite/append 操作写入的文本内容；replace 操作中表示查找文本。
destinationNocopy/move 操作的目标路径，必须在 MCP_WORKSPACE 内。
replacementNoreplace 操作使用的替换文本。
queryNogrep 操作使用的正则表达式；也可作为 replace 的查找文本。
patternNofind/grep 使用的 glob 文件匹配模式。*
recursiveNolist/delete 操作是否递归处理目录。
overwriteNowrite/copy/move 目标已存在时是否覆盖。
include_hashNoinfo 操作是否计算普通文件 SHA-256。
regexNoreplace 操作是否按正则表达式查找。
case_sensitiveNogrep 操作是否区分大小写。
start_lineNoread_lines 从第几行开始读取，行号从 1 开始。
max_linesNoread_lines 最多返回行数，实际限制在 1 到 1000。
max_charsNoread 最多返回字符数，实际限制在 1 到 MCP_MAX_FILE_BYTES。
max_entriesNolist/find/grep 最多返回条目数，实际限制在 1 到 1000。
countNoreplace 最多替换次数；0 表示全部替换。

Output Schema

ParametersJSON Schema
NameRequiredDescription

No output parameters

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavioral traits. It only mentions the write permission requirement, but fails to describe error handling, side effects, idempotency, or safety for other operations. This is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that conveys the essential purpose and a key behavioral constraint. It is efficiently front-loaded with the scope and permission condition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite the complexity (17 parameters, 13 actions), the description is minimal. It covers the workspace scope and write permission but lacks details on typical use cases, return values (though output schema exists), or guidance on action selection. The schema covers parameter details, but the context is sparse.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The tool description does not add extra meaning beyond the schema; it only mentions the write requirement which is already implied by the action enum.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool executes file operations within MCP_WORKSPACE, distinct from sibling tools (agent, web_search). The verb 'execute file operations' and resource 'MCP_WORKSPACE' are specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description indicates that write/copy/move/delete operations require MCP_ALLOW_WRITE=true, providing clear context. No explicit exclusions or alternatives are needed given sibling tools are unrelated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedagent
    • First observedfile_operation
    • First observedweb_search
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.5/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a clearly distinct domain: agent manages task state, file_operation handles files, and web_search performs internet searches. There is no overlap or ambiguity.

Naming Consistency5/5

All tool names follow a consistent pattern of lowercase with underscores (agent, file_operation, web_search), making them predictable and easy to distinguish.

Tool Count4/5

With 3 tools, the server is minimal but focused on essential utilities (task management, file ops, web search). It is slightly on the low end but appropriate for its stated purpose.

Completeness3/5

The set covers basic utility functions but lacks other common toolkit operations like code execution, data processing, or API calls, making it somewhat incomplete for a general 'Toolkit' server.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers