MCP Servers

A collection of Model Context Protocol servers, templates, tools and more.

T
Termux MCP
by @linhanhan227
GitHub Repo(1 stars)

MCP server by linhanhan227

Created 5/31/2026
Updated about 6 hours ago
README
View Source
Repository documentation and setup instructions

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|streamable-http | 覆盖 MCP_TRANSPORT。 | | --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。

Quick Setup
Installation guide for this server

Install Package (if required)

uvx termux-mcp

Cursor configuration (mcp.json)

{ "mcpServers": { "linhanhan227-termux-mcp": { "command": "uvx", "args": [ "termux-mcp" ] } } }