最近在做 AI Agent 相关的工程化改造最直观的感受是模型能力已经不是瓶颈“怎么让模型安全、稳定地访问企业内部数据和工具”才是核心难点。MCP 协议出现之后这个问题的解法在快速收敛但新的问题也随之而来——生态里的 MCP Server 越来越多散布在 GitHub、博客、技术群和各类分享帖子里想找到靠谱的那一个反而变成了难事。AllMCPs 正是这样一款面向 MCP Server 的社区目录项目它解决的是“发现、筛选、接入”这一整条链路的问题。本文会从 MCP 基础概念讲起结合 AllMCPs 的实际使用场景完整演示如何找到并接入一个 MCP Server再带你用 FastMCP 写一个属于自己的 Server 并提交收录最后给出一份常用排错清单与安全建议。1. MCP 与 MCP Server 的基本概念1.1 什么是 MCPMCP 全称 Model Context Protocol即模型上下文协议。它最早由 Anthropic 提出并开源目标是统一大模型与外部数据、工具之间的通信方式。在没有 MCP 之前开发者让 AI 调用外部能力的方式通常是为每个场景定制函数调用逻辑接入数据库写一套 SQL 解析接入飞书写一套 Webhook 封装接入浏览器自动化再写一套 Playwright 脚本。每套实现都不一样换一个客户端或者换一个模型原有的接入代码基本就要重写。MCP 的思路是定义一个标准协议把“模型要用的能力”抽象成服务端提供的一组能力接口。AI 客户端只需要实现一次 MCP Client就可以复用所有符合协议的 MCP Server。官方架构里通常分为三层AI 客户端Claude Desktop、Cursor、自研 Agent 等 ↓ MCP Client协议客户端 ↓ stdio / HTTP 传输 ↓ MCP Server工具、资源、提示词MCP Server 是协议中的服务端负责把真实能力暴露给客户端。它可以是一个本地 Python 进程也可以是一个 Docker 容器还可以是部署在远程服务器上的 HTTP 服务。客户端启动 Server 后会通过 JSON-RPC 的方式进行能力协商和方法调用。1.2 MCP Server 能提供什么能力MCP Server 主要向 AI 客户端暴露三类能力Tools可调用的函数工具。模型在对话过程中可以主动选择调用比如查询天气、执行 SQL、创建 GitHub Issue。Tools 通常意味着“模型可以发起操作”所以要关注权限控制。Resources可读取的资源。比如本地文件内容、数据库查询结果、API 返回数据。Resources 更偏读取型适合给模型提供上下文。Prompts可复用的提示词模板。比如“代码审查建议”“周报生成器”。模型可以根据模板快速产出结构化内容。对普通开发者来说日常接触最多的就是 Tools。一个成熟一点的 MCP Server 通常会同时暴露多个 Tool例如一个数据库 MCP Server 可以提供 list_tables、query、describe_table 等工具。1.3 为什么需要 AllMCPs 这样的目录MCP 生态在短时间内爆发GitHub 上已经出现大量各具特色的 Server。没有目录时开发者的典型困境是搜索成本高同一个“数据库 MCP Server”可能有几十个不同仓库不知道哪个还在维护。质量参差不齐有些项目只有几行说明既没有安装命令也没有安全说明跑起来才发现要读写任意文件。配置格式混乱不同 Server 的环境变量、启动参数、客户端配置方式各不相同一个个试过去非常耗时。AllMCPs 的角色类似于 npm 官网之于 npm 包、Homebrew Formulae 之于 Homebrew 包。它把分散的 MCP Server 信息聚合到一个统一入口提供分类、搜索、质量信号GitHub 星标、更新状态、用户反馈等元信息帮助开发者更快做出选择。1.4 哪些读者适合关注 AllMCPs如果你属于以下任意一类本文的内容都会对你有直接帮助后端开发或 Agent 应用开发者希望让 AI 安全地访问业务数据使用 Claude Desktop、Cursor、VS Code 等 AI 编程工具的工程师已经写好了一个 MCP Server希望被更多用户发现的开源作者。2. AllMCPs 核心功能拆解2.1 你可以在目录里做什么AllMCPs 本质上是一个带搜索能力的目录站。不同版本的页面交互可能会有调整但核心功能通常包括下面几类按关键词搜索 Server输入 sqlite、github、slack、postgres 等快速定位相关项目。按分类或标签浏览文件系统、数据库、浏览器自动化、开发者工具、消息通知等常见分类。查看 Server 详情包括 GitHub 仓库地址、项目简介、安装方式、权限说明和社区反馈。提交新的 Server如果你维护了一个开源 MCP Server可以通过提交入口让项目出现在目录中。你可以把它理解成一个“MCP Server 的起点页”。不需要记住大量零散的 GitHub 链接只需要记住一个入口然后按需搜索。2.2 如何评估一个 MCP Server 的质量从目录里看到一个 Server 后不要急着执行安装命令。建议按下面四个维度做一次快速体检评估维度需要确认的问题风险提示项目活跃度最近一次 commit 是什么时候有多少个 issue 长时间无人回复长期不维护的项目可能无法兼容新版客户端文档完整度README 是否包含安装命令、配置项说明、权限说明文档越模糊越容易踩坑安全边界Server 是否只做最小必要操作是否建议以容器运行权限过大可能造成本地文件泄露或数据损坏协议实现方式是否基于官方 SDK是否使用 npx/npm 标准安装自制协议实现容易在版本更新后失效这里额外强调一下安全边界。MCP Server 在本地运行时通常拥有当前用户的权限可以读写文件、调用命令、访问网络。如果一个第三方 Server 明确要求你提供高权限 Token或者 README 里写它需要“读取整个用户目录”就要高度警惕。最理想的做法是先阅读源码再在隔离环境试运行最后才接入主用客户端。2.3 注册与提交自己的 ServerAllMCPs 收录的大多数是开源的 MCP Server。如果你希望自己的项目被收录一般需要走这么几步项目公开仓库必须是一个可公开访问的 Git 仓库例如 GitHub、Gitee 或 GitLab。README 清晰至少包含项目用途、安装方式、运行命令、环境变量说明。提供可运行示例最好在 README 里给出一份客户端配置文件片段。填写提交信息在 AllMCPs 的提交入口填写仓库地址、标题、简介、分类和标签等待维护者审核。提交前一定要想清楚一个问题这个项目是否真的对社区开放不要把一个写死内部地址、硬编码密钥的仓库提交到公开目录。目录维护者通常会对提交做人工审核但作为作者你才是第一责任人。3. 环境准备与前置知识3.1 你需要准备什么本文后续的实战会涉及本地运行 MCP Server以及编写自己的 Server。建议提前准备以下环境Python 3.10 或更高版本推荐 3.11用于后续 FastMCP 示例Node.js 18 或更高版本部分 Server 需要通过 npx 启动一个支持 MCP 的客户端例如 Claude Desktop、Cursor、VS Code 或自研客户端Git用于克隆项目并发布自己的代码Docker可选用于隔离运行第三方 Server。版本号以你实际安装时为准。不同版本的 MCP SDK 和客户端对协议的支持会有差异遇到版本相关的报错先看官方 release notes再决定是否升级。3.2 MCP 客户端如何配置 Server大多数桌面客户端通过在配置文件中声明 MCP Server 列表来实现接入。以 Claude Desktop 为例配置文件通常为claude_desktop_config.json基本格式如下{ mcpServers: { server-demo: { command: npx, args: [ -y, example/mcp-server-demo ], env: { SOME_API_KEY: your-key-here } } } }字段含义mcpServersMCP Server 的集合对象key 是自定义名称。command启动该 Server 的可执行命令。args命令参数通常包括包名和运行时参数。env注入给 Server 进程的环境变量。不同客户端的配置入口略有不同Claude Desktop 是全局配置文件Cursor 和 VS Code 通常支持项目级的.cursor/mcp.json或.vscode/mcp.json。具体路径请以你使用的客户端官方文档为准。3.3 两种典型的运行方式MCP Server 最常见的运行方式有两种本地进程方式客户端通过 stdio 启动一个子进程双方通过标准输入输出传输 JSON-RPC 消息。这种方式配置简单适合个人开发环境。远程 HTTP 方式客户端通过 HTTP 访问远程部署的 MCP Server。这种方式适合团队共享能力但需要考虑认证、限流和数据安全。本文后续示例以本地进程方式为主这也是 AllMCPs 上大量 Server 的默认运行方式。4. 实战一从 AllMCPs 找到并接入一个真实 Server4.1 场景设定假设你的需求是让 AI 助手能够查询和分析本地 SQLite 数据库。你希望模型可以列出数据库中的所有表、查看表结构并执行简单的查询。这个场景非常适合用 MCP 实现因为 SQLite 是本地文件不需要额外启动数据库服务而且官方有参考实现。4.2 在目录中找到合适的 Server打开 AllMCPs在搜索框输入sqlite或database。搜索结果会出现多个相关项目。我会优先选择符合以下特征的项目基于官方 SDK 实现安装命令是标准的npx -y或uvxREADME 里明确说明可以访问哪些路径以及默认权限大小项目更新频率较高最近一次提交在一个季度以内使用人数相对多社区反馈正常。以官方参考实现modelcontextprotocol/server-sqlite为例它的作用是暴露一个 SQLite 数据库文件给模型支持查询和表结构读取。注意包名和具体行为可能会随版本变化实际使用前请查看对应仓库说明。4.3 本地运行一个 SQLite Server首先创建一个测试数据库文件mkdir -p ~/mcp-demo cd ~/mcp-demo sqlite3 test.db CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT, email TEXT); INSERT INTO users (name, email) VALUES (Tom, tomexample.com);如果你的系统没有安装 sqlite3 命令行工具也可以提前在任意 SQLite 管理工具中创建该文件。然后尝试手动启动 Servernpx -y modelcontextprotocol/server-sqlite ~/mcp-demo/test.db如果依赖安装成功进程会保持前台运行等待客户端通过 stdio 连接。此时看不到明显输出是正常的说明 Server 正在等待消息。如果你更希望用 Docker 隔离第三方 Server可以参考下面这种通用结构docker run -i --rm \ -v $PWD:/data \ -e SOME_API_KEYyour-key \ mcp/example-server \ --path /data/test.db容器方式的好处是第三方 Server 即使出现异常也无法直接访问宿主机的其他目录。但代价是网络、文件挂载和密钥注入需要额外配置复杂度会高一些。4.4 在客户端中配置并验证在 Claude Desktop 的claude_desktop_config.json中添加如下配置{ mcpServers: { sqlite-demo: { command: npx, args: [ -y, modelcontextprotocol/server-sqlite, /absolute/path/to/mcp-demo/test.db ] } } }注意两点args中的路径必须写绝对路径相对路径在部分客户端中会被解析到不同的工作目录。修改配置后需要完全重启客户端不能只刷新窗口。重启后在聊天框中输入类似这样的话请查看当前数据库中有哪些表然后查询 users 表的前 3 条数据。如果配置成功模型会自动调用 MCP Server 提供的工具返回表结构信息和查询结果。你可以在客户端日志或 MCP 工具调用面板中看到对应的调用记录。4.5 预期结果与说明正常情况下你会看到模型先调用类似list_tables的工具再调用类似query的工具最后基于工具返回结果做总结。这里要强调一点模型返回的数据是 Server 返回的真实查询结果不是模型的“猜测”。这也是 MCP 的核心价值之一把“事实查询”和“语言生成”分开模型只负责基于结果组织语言。如果你的客户端没有显示工具调用请先检查配置文件路径和 Server 启动命令然后参考第 6 章的排查清单。5. 实战二用 FastMCP 编写自己的 Server 并提交收录5.1 为什么要自建 MCP Server使用现成的 Server 能解决不少问题但团队内部往往有一些私有能力需要暴露给 AI 客户端。举几个典型场景内部订单系统的只读查询接口基于公司知识库的检索工具封装好的运维脚本只允许特定角色调用。这时候自己写一个 MCP Server 是最可控的方案。下面我们使用 Python 官方 SDK 中的 FastMCP 来构建一个最小可用的 Server。5.2 创建项目结构先安装依赖pip install mcp[cli]然后创建如下项目结构my-mcp-server/ ├── pyproject.toml ├── weather_server.py └── README.mdpyproject.toml是项目元数据文件你可以先用最简配置[project] name weather-mcp-server version 0.1.0 description A demo MCP server for weather queries requires-python 3.105.3 编写核心代码这里实现一个天气查询工具。为了便于演示我们不接入真实天气 API而是使用本地演示数据。真实项目中你只需要在函数内部替换成 HTTP 调用或数据库查询即可。文件路径weather_server.pyfrom mcp.server.fastmcp import FastMCP # 创建一个 MCP Server 实例 mcp FastMCP(weather-demo) # 定义演示用天气数据 DEMO_WEATHER { 北京: 晴最高 18℃最低 5℃空气质量良, 上海: 多云最高 20℃最低 12℃空气质量优, 广州: 小雨最高 24℃最低 18℃空气质量优, } mcp.tool() def get_weather(city: str) - str: 查询指定城市的天气信息演示数据 return DEMO_WEATHER.get(city, f暂无 {city} 的天气数据请尝试北京、上海或广州) if __name__ __main__: # 以 stdio 方式运行 Server mcp.run()代码解释FastMCP(weather-demo)创建 Server 实例名称会显示在客户端工具列表中。mcp.tool()将这个函数注册为 Tool。函数名get_weather是模型调用时的工具名。city: str参数声明模型会依据函数签名自动生成调用参数。返回的字符串会被序列化为工具输出再交给模型总结。这个示例虽然简单但已经包含了 MCP Server 的核心结构。真实场景中你可以在get_weather内部加入更复杂的业务逻辑例如查询订单、检索文档或调用内部 API。5.4 本地调试与验证运行 Serverpython weather_server.py如果程序没有报错并保持前台运行说明 Server 可以启动。接下来建议使用 MCP Inspector 做一次更完整的交互验证npx modelcontextprotocol/inspector python weather_server.pyInspector 会启动一个本地调试面板你可以在面板中看到 Server 暴露的 Tool 列表并手动触发get_weather调用查看返回结果。这一步非常重要。不要等到提交到 AllMCPs 之后才发现在客户端里无法运行。本地验证通过再进入下一步。5.5 发布到 GitHub 并提交到 AllMCPs当你的 Server 本地调试通过后就可以准备发布。首先保证仓库包含以下文件weather_server.py核心代码pyproject.toml项目元数据与依赖声明README.md安装命令、运行方式、配置说明LICENSE 文件开源许可证可选claude_desktop_config.json示例片段。README 中建议给出最小配置示例方便用户直接复制{ mcpServers: { weather-demo: { command: python, args: [ /abs/path/to/weather_server.py ] } } }然后执行 Git 提交并推送到远程仓库git init git add . git commit -m feat: init weather mcp server git branch -M main git remote add origin gitgithub.com:yourname/weather-mcp-server.git git push -u origin main最后进入 AllMCPs 的提交入口填写仓库地址和简介。审核通过后你的 Server 就会出现在目录中。这里有一个建议不要为了追求收录数量而提交半成品。一个 README 清晰、能直接跑通、权限边界明确的开源项目比一百个空仓库更有价值。5.6 提交后的维护当 MCP SDK 发布大版本更新时及时测试兼容性并升级如果用户反馈安全或权限问题优先处理并发布修复版本项目停更时在 README 中标注 archived避免新用户误用。6. 常见问题与排查思路6.1 常见问题汇总问题现象常见原因解决思路客户端中看不到配置的 Server 工具配置路径错误、未完全重启、Server 启动失败检查配置文件位置和参数查看客户端日志先用命令行手动启动同一命令启动报 command not found / ENOENTNode.js 或 npx 不在 PATH路径写成了相对路径使用绝对路径调用在终端确认npx --version可用工具能调用但返回超时远程接口响应慢或进程阻塞在 Server 内部增加超时控制使用 MCP Inspector 单独测试Docker 容器内无法访问宿主机文件未挂载 volume或路径映射错误检查-v挂载参数容器内使用绝对路径Server 启动但直接退出缺少环境变量、端口被占用或缺少依赖查看启动时的报错信息对比 README 检查 env 配置模型始终不调用某个 Tool工具描述不清晰或模型判断不需要使用优化函数 docstring用更明确的提示词引导模型6.2 排查的一般顺序遇到问题时建议按下面的顺序排查而不是盲目改配置先手动启动一次 Server确认它本身能正常工作。检查客户端配置文件是否是合法 JSON路径是否为绝对路径。查看客户端日志找到 MCP 连接相关的报错信息。用 MCP Inspector 单独调试 Server排除客户端问题。最后才考虑切换版本或更换 Server 实现。7. 最佳实践与安全建议7.1 MCP Server 的安全边界MCP Server 的权限边界非常值得重视。一个运行在本地客户端的 Server默认拥有当前系统用户的权限。这意味着它可以读取你的文档、执行命令、访问网络。因此使用第三方 MCP Server 时至少做到以下几点不使用来源不明的 Server尤其是只给一行命令但没有任何源码公开的先阅读源码至少浏览 README 和入口文件优先使用 Docker 运行权限需求较大的 Server为不同 Server 创建单独的低权限 API Token不要复用主账号密钥定期回收不再使用的 Token 和 Server 配置。7.2 密钥与环境变量管理不要把 API Key 直接写在配置文件中更不要把包含密钥的 JSON 文件提交到 Git 仓库。建议的做法是通过环境变量注入。以下是一个示例{ mcpServers: { github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_PERSONAL_ACCESS_TOKEN: ${GITHUB_TOKEN} } } } }具体变量注入方式取决于你的客户端支持能力。无论如何配置文件如果包含敏感信息就要遵循最小访问原则只有当前用户可读写。7.3 日志与可观测性Server 上线后日志是排查问题最重要的依据。建议在你的 Server 中增加结构化日志至少包含请求工具名、调用参数、耗时和错误信息。在开发阶段可以把日志输出到 stderr生产环境则建议接入统一的日志收集系统。7.4 对目录维护者或开源作者的建议如果你维护一个 MCP Server 目录或打算在 AllMCPs 上提交项目建议参考以下原则用自动化方式拉取 GitHub 元数据辅助人工判断项目质量对长期不维护的项目增加“已归档”或“低活跃”标记在 README 中明确说明权限范围和适用场景不建议把只面向特定组织的内部工具提交到公开目录收到安全类 issue 后优先响应不要拖延。8. 总结与下一步学习路线8.1 本文关键要点回顾读完本文你应该已经掌握MCP 与 MCP Server 的核心概念以及 Tools、Resources、Prompts 三类能力AllMCPs 目录的核心功能与筛选 Server 的质量评估维度从目录中找到合适的 Server配置到本地 AI 客户端的完整流程使用 FastMCP 编写一个最小可用的 MCP Server并发布、提交收录常见的 MCP 配置问题排查思路使用 MCP Server 时的安全边界和密钥管理建议。8.2 下一步可以学什么如果你想让自己的 MCP 能力更进一步可以按下面的顺序继续学习阅读 MCP 官方规范理解协议传输层和 JSON-RPC 方法在自己的 Server 中实现 Resources 和 Prompts而不只是 Tools尝试把一个 Server 打包成 npm 包或 Python 包提供标准安装方式了解 Spring AI 等后端框架对 MCP 的支持探索服务端接入方案。8.3 给新手的实操建议不要停留在收藏文章这一步。先把第 4 节的 SQLite Server 跑通再改写成自己的业务工具。把项目跑起来之后再去读 MCP 规范文档你会发现之前不太理解的概念都变得顺理成章。实践永远是理解协议最好的方式。