项目简介

mcp-servers 是一个 Python 包，提供多种基于 Model Context Protocol (MCP) 的服务器实现，旨在为大型语言模型 (LLM) 客户端或 AI Agent 提供标准化的上下文信息和外部能力（工具）。

主要功能点

文件系统服务器: 提供沙盒化的文件访问能力，允许 AI Agent 在指定目录内执行文件列表、读写、移动、删除、创建目录等操作。
Brave Search 服务器: 封装 Brave Search API，使 AI Agent 能够通过 MCP 工具进行网络搜索。
SearXNG Search 服务器: 封装 SearXNG API，使 AI Agent 能够通过 MCP 工具调用自托管或公共 SearXNG 实例进行网络搜索。
Tavily Search 服务器: 封装 Tavily AI Search API，使 AI Agent 能够进行网络搜索、网页内容提取和网页抓取。
CLI 工具: 提供 'mcpserver' 命令行工具，方便管理配置、启动/停止服务器、管理外部依赖容器。
HTTP/SSE 协议: 服务器通过 HTTP/SSE 传输协议与 MCP 客户端通信。

安装步骤

确保 Python 3.12+ 已安装。

推荐使用 'uv' 进行安装（如果未安装，请先安装 uv: 'pip install uv'）：

uv venv --python 3.12
source .venv/bin/activate
uv pip install --upgrade mcp-servers

或者使用 'pip'：

pip install --upgrade mcp-servers

服务器配置 (供MCP客户端参考)

MCP 客户端需要配置 MCP 服务器的连接信息，通常包含服务器名称、启动命令及其参数。以下是 'mcpserver' CLI 工具启动各种服务器时使用的典型命令行参数，可用于构建 MCP 客户端的配置 JSON（示例中假设客户端通过 'command' 和 'args' 字段来定义如何启动服务器进程）：

// 文件系统服务器配置示例
{
  "name": "mcp_server_filesystem",
  "command": "mcpserver",
  "args": [
    "start",
    "--server", "filesystem",
    "--host", "0.0.0.0", // 服务器监听地址，可根据实际情况修改
    "--port", "8765",     // 服务器监听端口，可根据实际情况修改
    "--allowed-dir", "/path/to/your/sandbox" // 指定沙盒目录，请替换为实际路径
    // 可选参数: "--detach" 在后台运行
  ]
}

// Brave Search 服务器配置示例
{
  "name": "mcp_server_brave_search",
  "command": "mcpserver",
  "args": [
    "start",
    "--server", "brave_search",
    "--host", "0.0.0.0", // 服务器监听地址，可根据实际情况修改
    "--port", "8766"     // 服务器监听端口，可根据实际情况修改
    // 需要在 ~/.mcp_servers/.env 中配置 BRAVE_API_KEY
    // 可选参数: "--detach" 在后台运行
  ]
}

// SearXNG Search 服务器配置示例
{
  "name": "mcp_server_searxng_search",
  "command": "mcpserver",
  "args": [
    "start",
    "--server", "searxng_search",
    "--host", "0.0.0.0", // 服务器监听地址，可根据实际情况修改
    "--port", "8767"     // 服务器监听端口，可根据实际情况修改
    // 需要在 ~/.mcp_servers/.env 中配置 SEARXNG_BASE_URL (如 http://0.0.0.0:8001)
    // 可选参数: "--detach" 在后台运行
  ]
}

// Tavily Search 服务器配置示例
{
  "name": "mcp_server_tavily_search",
  "command": "mcpserver",
  "args": [
    "start",
    "--server", "tavily_search",
    "--host", "0.0.0.0", // 服务器监听地址，可根据实际情况修改
    "--port", "8768"     // 服务器监听端口，可根据实际情况修改
    // 需要在 ~/.mcp_servers/.env 中配置 TAVILY_API_KEY
    // 可选参数: "--detach" 在后台运行
  ]
}

在启动 MCP 服务器之前，请务必运行 'mcpserver init' 命令初始化配置文件，并在 '~/.mcp_servers/.env' 文件中填入必要的 API Key 和基础 URL。对于 SearXNG，如果使用本地实例，还需要先运行 'mcpserver run_external_container --container searxng'。

基本使用方法

初始化配置: 打开终端，运行 'mcpserver init'。根据提示或手动编辑 '~/.mcp_servers/.env' 填入 API Key 等信息。如果需要使用 SearXNG 本地实例，初始化还会生成 SearXNG 配置文件。
启动 SearXNG 容器 (如果需要): 如果你的 MCP SearXNG 服务器连接的是本地 SearXNG 容器，确保已安装 Docker 或 Podman，并在终端运行 'mcpserver run_external_container --container searxng' 启动容器。
启动 MCP 服务器: 根据需要，在终端使用 'mcpserver start' 命令启动一个或多个 MCP 服务器。例如，启动文件系统服务器：
```
mcpserver start --server filesystem --allowed-dir /path/to/your/sandbox
```
启动 Brave Search 服务器 (需要在 '.env' 配置 'BRAVE_API_KEY')：
```
mcpserver start --server brave_search
```
你可以通过 '--port' 参数指定不同端口同时运行多个服务器，并通过 '--detach' 参数在后台运行。
MCP 客户端连接: 启动服务器后，你的 MCP 客户端（例如使用 'pydantic_ai' 库的 Agent）即可通过 HTTP/SSE 连接到服务器指定的地址和端口 ('http://<host>:<port>/sse')，并开始调用服务器提供的工具。参考仓库中的 'examples/cli_usage' 或 'examples/package_usage' 示例代码，了解如何从 Python 代码中连接到服务器并使用 Agent 调用工具。

停止服务器: 对于在前台运行的服务器，按 'Ctrl+C' 停止。对于使用 '--detach' 在后台运行的服务器，使用 'mcpserver stop --server <server_name> [--port <port>]' 命令停止。例如：

mcpserver stop --server filesystem

停止 SearXNG 容器：

mcpserver stop_external_container --container searxng

关键词

项目简介

主要功能点

安装步骤

服务器配置 (供MCP客户端参考)

基本使用方法

信息