Model Context Protocol servers 仓库实战指南：七个官方 MCP 参考服务器的运行、配置与源码剖析

MCP（Model Context Protocol）服务器仓库（modelcontextprotocol/servers）集中了由 MCP 指导小组维护的参考实现（reference implementations），其目标是示范 MCP 协议特性与官方 SDK 的用法，而非提供生产级解决方案。本文以仓库根目录 README.md 为主线，完整继承其中的服务器清单、启动命令与客户端配置示例，并结合各服务器的源码、子 README 与测试用例做纵深展开，帮助读者在 MCP 客户端（如 Claude Desktop、VS Code、Zed）中真正跑通这些服务器，并理解其目录访问控制、持久化存储与发布机制等底层实现。

一、仓库定位：参考实现，而非生产服务

README.md 开篇即给出两条重要提示：

1. 服务器列表入口已迁移：如果你只是想找一份"所有 MCP 服务器"的清单，官方 MCP Registry 是浏览已发布服务器的入口；本仓库只承载 MCP 指导小组维护的那一小撮参考服务器。
2. 安全警告（WARNING）：本仓库中的服务器是参考实现，用于演示 MCP 特性和 SDK 用法，是面向"要自建 MCP 服务器"的developers 的教学示例，不是生产就绪方案。开发者应根据自身的威胁模型和用例评估安全需求并实现相应的防护。

这一立场在 SECURITY.md 中被再次强调：本仓库的服务器"不作为生产就绪方案"，且本仓库本身不接受安全漏洞报告——如果你在某个 MCP SDK 中发现了漏洞，应通过 GitHub Security Advisory 流程在对应 SDK 仓库中报告，而不是通过公开 issue。

仓库的 README 还指出：这些服务器展示了 MCP 的多样性和可扩展性，说明如何为 LLM 提供安全、受控的工具与数据源访问能力。从源码结构看，绝大多数服务器都是用官方 MCP SDK 实现的——README 列举了 C#、Go、Java、Kotlin、PHP、Python、Ruby、Rust、Swift、TypeScript 共 10 个官方 SDK；本仓库内实际落地的是 TypeScript SDK（4 个 Node 服务器）与 Python SDK（3 个 Python 服务器）。

二、七个参考服务器总览与逐项深入

README 的 "Reference Servers" 一节列出了当前维护的 7 个服务器。下表的描述直接继承自 README.md，包名与版本信息则来自各子包的 package.json / pyproject.toml。

服务器	源码位置	npm/PyPI 包名	一句话定位
Everything	src/everything	@modelcontextprotocol/server-everything v2.0.0	覆盖 prompts、resources、tools 的参考/测试服务器
Fetch	src/fetch	mcp-server-fetch v0.6.3	抓取网页并转换为 Markdown，供 LLM 高效消费
Filesystem	src/filesystem	@modelcontextprotocol/server-filesystem v0.6.3	带可配置访问控制的文件操作
Git	src/git	mcp-server-git v0.6.2	读取、搜索、操作 Git 仓库的工具集
Memory	src/memory	@modelcontextprotocol/server-memory v0.6.3	基于知识图谱的持久记忆系统
Sequential Thinking	src/sequentialthinking	@modelcontextprotocol/server-sequential-thinking v0.6.2	通过"思考序列"做动态、反思式的问题求解
Time	src/time	mcp-server-time v0.6.2	时间查询与时区转换

2.1 Everything：一个协议特性的"全量演练场"

Everything 服务器的定位是"演练 MCP 协议全部特性的参考/测试服务器"，它同时提供 prompts、resources 和 tools。从 src/everything/index.ts 的入口代码可以看到它的启动方式支持三种传输（transport）：

node dist/index.js stdio           # 默认，stdin/stdout
node dist/index.js sse             # HTTP + SSE
node dist/index.js streamableHttp  # Streamable HTTP

入口通过 process.argv 解析传输名，并动态 import 对应的 transports/stdio.js、transports/sse.js、transports/streamableHttp.js 模块，避免未选中的传输模块被初始化（见 src/everything/index.ts）。配合 package.json 中的 start:stdio / start:sse / start:streamableHttp 三个 npm script，它就是三种传输方式的官方演示样例。其 __tests__ 目录下按 prompts、registrations、resources、server、tools 五份测试文件分模块验证，也是研究"如何给 MCP 服务器写单元测试"的好样本。

2.2 Memory：知识图谱持久记忆

Memory 用本地知识图谱实现跨会话持久记忆，核心概念分三层（见 src/memory/index.ts 的接口定义）：

• Entities（实体）：图的节点，含唯一 name、entityType（如 person / organization）和 observations 列表。示例：{"name": "John_Smith", "entityType": "person", "observations": ["Speaks fluent Spanish"]}。
• Relations（关系）：实体间的有向连接，始终以主动语态存储，如 {"from": "John_Smith", "to": "Anthropic", "relationType": "works_at"}。
• Observations（观察）：挂在实体上的原子化事实字符串，可独立增删。

它提供 9 个工具：create_entities、create_relations、add_observations、delete_entities、delete_observations、delete_relations、read_graph、search_nodes（跨实体名/类型/观察内容检索）、open_nodes（按名取节点），外加一个资源 memory://knowledge-graph（MIME 为 application/json，形状与 read_graph 相同）。各删除/变更工具有明确的幂等语义：create_entities 忽略重名实体、delete_* 对不存在的对象静默处理，而 add_observations 在实体不存在时会失败——这种差异化的容错设计值得自建服务器时参考。

源码层面有几个值得注意的实现细节（见 src/memory/index.ts）：

• 存储路径可配置：环境变量 MEMORY_FILE_PATH 指定自定义 JSONL 文件；未设置时默认使用服务器目录下的 memory.jsonl，并且内置了从旧格式 memory.json 到 memory.jsonl 的自动迁移逻辑（ensureMemoryFilePath）。
• JSONL 格式落盘：KnowledgeGraphManager 的 saveGraph 把每个实体/关系序列化为独立 JSON 行写入文件（src/memory/index.ts），追加与审计都更友好。
• 该服务器还演示了 notifications/resources/updated 订阅更新：变更工具触发后，订阅了 memory://knowledge-graph 的客户端能收到实时变更通知。

README.md 中的启动命令示例正是以 Memory 为例：

npx -y @modelcontextprotocol/server-memory

2.3 Filesystem：目录白名单 + Roots 动态授权

Filesystem 提供 read_text_file、read_media_file、write_file、edit_file（支持 dry-run 预览与 Git 风格 diff）、create_directory、list_directory(_with_sizes)、move_file、search_files、directory_tree、get_file_info、list_allowed_directories 等工具，所有操作都受目录白名单约束。白名单有两条注入途径：

1. 命令行参数：mcp-server-filesystem /path/to/dir1 /path/to/dir2；
2. MCP Roots（官方推荐）：客户端在 initialize 时若声明支持 roots，服务器会发起 roots/list 请求，用客户端提供的 roots 完全替换服务端白名单；运行时客户端还可发送 notifications/roots/list_changed 动态更新，无需重启。

一条关键行为（来自 src/filesystem/README.md 并可在 roots-utils.ts / path-validation.ts 中找到对应实现）：若服务器未带任何命令行参数启动，且客户端不支持 roots 协议（或返回空 roots），服务器将在初始化时抛错——至少需要一个允许目录，否则整个服务器不工作。这等于把"默认拒绝"做成了强制语义。

子 README 还给出了一张工具注解（ToolAnnotations）映射表：所有读工具 readOnlyHint: true，write_file 标记 destructiveHint: true（会覆盖已有文件）、edit_file/move_file 非幂等等，且每个工具都设置 openWorldHint: false，表明该服务器不触达开放/外部世界。

2.4 Git：仓库内路径的双重校验

mcp-server-git 提供 git_status、git_diff / git_diff_staged / git_diff_unstaged、git_commit、git_add 等读写类工具（部分工具如 git_diff 支持 context_lines 参数，默认 3）。README 提醒该服务器仍处早期开发阶段，功能可能变化。

从源码看它有两道安全防线（src/git/src/mcp_server_git/server.py）：

• 启动参数 --repository 可把服务器限定在某个仓库内；不带该参数时服务器不绑定仓库（serve(None)）。
• 每次工具调用都会执行 validate_repo_path：把 repo_path 解析为绝对路径后，校验它必须是允许仓库本身或其子目录，越界即拒绝。注释里明确写着 "Defense in depth"——防止在仓库边界外暂存/操作文件。

README.md 给出的客户端示例恰好演示了 --repository 参数："args": ["mcp-server-git", "--repository", "path/to/git/repo"]。Python 包的启动入口是 mcp_server_git:main（见 src/git/pyproject.toml 的 [project.scripts]，mcp-server-git 与 python -m mcp_server_git 等价，入口实现于 src/git/src/mcp_server_git/main.py）。

2.5 Fetch、Time 与 Sequential Thinking

• Fetch：单一 fetch 工具，把 URL 内容抓下来并转成 Markdown。参数：url（必填）、max_length（默认 5000 字符）、start_index（从该字符偏移继续抽取，支持分块读取长页面）、raw（跳过 Markdown 转换）。它带一个明确的安全警示：该服务器可以访问本地/内网 IP 地址，存在暴露敏感数据的风险，使用时要谨慎。此外它还演示了 Prompts 能力（提供一个同名 fetch prompt）。
• Time：get_current_time（参数为 IANA 时区名，如 America/New_York）与 convert_time（源时区 + 24 小时制 HH:MM + 目标时区）两个工具。默认自动检测系统时区，可用 --local-timezone 参数覆盖（Docker 下对应 LOCAL_TIMEZONE 环境变量）。从源码看（src/time/src/mcp_server_time/server.py），时区解析失败会抛出 INVALID_PARAMS 的 McpError，转换结果包含 is_dst（夏令时标志）与 time_difference（对尼泊尔 UTC+5:45 这类非整点偏移做了专门格式化）。
• Sequential Thinking：通过结构化的"思考序列"工具支持 LLM 的动态、反思式问题求解，是官方 SDK 的纯 TypeScript 实现之一（@modelcontextprotocol/server-sequential-thinking）。

三、快速开始：npx、uvx 与 pip 三种启动方式

README.md 的 Getting Started 部分区分了两类运行时：

TypeScript 服务器直接用 npx（无需本地安装，-y 自动确认）：

# Memory 服务器
npx -y @modelcontextprotocol/server-memory

# Filesystem 服务器（后面直接跟允许的目录）
npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/files

Python 服务器用 uvx 或 pip，官方推荐 uvx（免安装、环境隔离）：

# Git 服务器，二选一
uvx mcp-server-git
# 或
pip install mcp-server-git
python -m mcp_server_git

适用前提：TypeScript 服务器需要 Node.js 环境；Python 服务器需要 Python ≥ 3.10（各 pyproject.toml 中 requires-python = ">=3.10"），并先用官方渠道安装 uv/uvx 或 pip。

配置进 MCP 客户端

README 强调：单独运行一个服务器意义不大，它应该被配置进 MCP 客户端。以 Claude Desktop 为例，最小配置：

{
  "mcpServers": {
    "memory": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

Windows 下必须用 cmd /c 包裹 npx（README 明确给出的跨平台写法）：

{
  "mcpServers": {
    "memory": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-memory"]
    }
  }
}

README 还给出了一段多服务器组合示例，完整继承如下（其中 github / postgres 两项指向已归档的历史参考实现，作为配置语法示例保留）：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
    },
    "git": {
      "command": "uvx",
      "args": ["mcp-server-git", "--repository", "path/to/git/repo"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

README 补充的 Windows 规则：对所有 npx 条目把 "command" 改为 "cmd" 并在 args 前部加上 "/c", "npx"，而 uvx 条目保持不变。注意 env 字段是传递凭据（如 GITHUB_PERSONAL_ACCESS_TOKEN）的标准位置。

各服务器子 README 还给出了 Docker 方式（如 Memory 的 docker run -i -v claude-memory:/app/dist --rm mcp/memory、Filesystem 需把所有允许目录挂载到 /projects、只读挂载加 ro）以及 VS Code 的 .vscode/mcp.json 写法，可按需深入对应子目录文档。

四、已归档的参考服务器

README 的 "Archived" 一节列出已移出本仓库、转存到 servers-archived 仓库的历史服务器，包括：AWS KB Retrieval、Brave Search、EverArt、GitHub、GitLab、Google Drive、Google Maps、PostgreSQL、Puppeteer、Redis、Sentry、Slack、SQLite。其中部分已被官方或第三方替代（如 Brave Search 由 Brave 官方服务器接替，Slack 由 Zencoder 社区维护）。这条归档线说明仓库的取舍标准：参考服务器只保留"能示范 MCP 协议特性"的那部分，偏第三方 API 集成的实现交给社区。

五、Monorepo 工程结构与发布机制

从仓库根 package.json 可以看清整体工程结构：

• npm workspaces 根项目 @modelcontextprotocol/servers（private: true，files: []，即根包不发布，只作为编排入口），workspace 通配 src/*；
• 根脚本 build / watch / publish-all / link-all 都以 --workspaces 广播到各子包；
• 通过 overrides 统一抬高了 qs、hono 等传递依赖版本，用于收敛安全漏洞。

发布流程记录在 RELEASING.md：所有包只能从 CI 的 release workflow 发布，由 release 环境的强制评审把关，采用 npm 与 PyPI 双端的 OIDC trusted publishing（无注册表令牌、带 provenance 声明）；版本采用日期制（CalVer）；每个包的发布是独立矩阵任务（fail-fast: false，互不阻塞），发布前先跑该包的测试（Python 端加 pyright）。失败后的补救方式是 gh run rerun <run-id> --failed，文档同时明确"绝不用本地 npm token 手工发布"。这对自建 MCP 服务器的安全发布有直接参考价值。

贡献规范见 CONTRIBUTING.md：官方不接受新的服务器实现（新服务器应发布到 MCP Registry），欢迎的是 bug 修复、可用性改进，以及"更能示范协议特性"的增强（例如给 filesystem-server 补 Roots 支持这类常被忽视的特性演示）；TypeScript 服务器的测试框架统一要求使用 vitest（仓库内各 src/*/vitest.config.ts 与该约定一致）。

六、延伸阅读：自建服务器与生态资源

README 指引读者到 MCP 官方文档学习"如何创建自己的 MCP 服务器"，并通过 ADDITIONAL.md 提供社区生态清单——按"服务器框架 / 客户端框架 / 资源"分类整理了数十个第三方项目（各类语言的 SDK 封装、FastAPI 一键转 MCP、MCP 代理与注册表索引等），可以作为选型起点。协议规范层面，文件系统服务器的注解表格对应 MCP 规范中的 ToolAnnotations 语义（readOnlyHint / idempotentHint / destructiveHint / openWorldHint），写自己服务器时照此标注能让客户端更好地做安全分级。

最后重申本仓库的边界：这 7 个服务器是教学与演示资产。它们的价值在于——用最小可读的代码把 tools、resources、prompts、roots、订阅通知、多传输、路径沙箱、持久化存储这些 MCP 核心概念各演示了一遍；把它们作为源码样板研究，再结合官方 SDK 构建面向生产的服务器，才是这个仓库设计的用法。