awesome-mcp-servers 贡献者入门:如何提交或认领一个 MCP 服务器条目(完整指南)
awesome-mcp-servers 贡献者入门:如何提交或认领一个 MCP 服务器条目(完整指南)
awesome-mcp-servers 是一个社区维护的 MCP(Model Context Protocol)服务器大全,目前收录了 7,700+ 个 MCP 服务器条目。本文面向新手贡献者,手把手教你在 awesome-mcp-servers 中提交一个新的 MCP 服务器条目、认领(Claim)自己维护的服务器 Profile,以及如何从"清理队列"这类低门槛任务开始你的第一次开源贡献。 🚀
仓库速览:MCP 服务器条目放在哪里
在动手之前,先花 1 分钟了解仓库结构,这决定了你的贡献应该改哪里:
| 内容 | 位置 | 说明 |
|---|---|---|
| 分类目录页 | docs/ 下的 *.md |
条目真正所在的"源头",每个分类一个文件 |
| 结构化元数据 | data/server-metadata/ | 每个服务器的 {serverId}.json 侧车文件 |
| 生成的目录数据 | data/catalog.json | 构建产物,不要手动编辑 |
| 生成的 Profile | data/profiles/ | 构建产物,不要手动编辑 |
| 元数据规范 | schemas/server-metadata.schema.json | 定义侧车文件的字段格式 |
📌 一句话总结:你只需要编辑 docs/ 下的分类页(简单条目)或额外加一个元数据侧车文件(高级条目),其余数据由构建流程自动生成。各构建脚本可在 package.json 中查看。
提交新 MCP 服务器条目:3 种方式任选
方式一:直接编辑分类页并提交 PR(最常用)
适合熟悉 Markdown 和 Pull Request 流程的贡献者:
-
从 README.md 的 Browse by Category 表格中,为服务器挑选最合适的一个分类;
-
打开对应的分类页,例如 docs/databases.md;
-
按现有条目格式新增一行 Markdown 列表项,例如:
- [你的服务器名](https://example.com/your-mcp-server): 简要说明这个 MCP 服务器能让 Agent 做什么。Install: `npx your-package`。 -
全文搜索仓库中你的 URL 或项目名,确认没有重复条目(这是新手最容易踩的坑);
-
提交 Pull Request,等待维护者审核。
方式二:填写 Add MCP server Issue 表单(最适合新手)
不确定放在哪个分类?可以直接使用仓库提供的 Add MCP server issue 表单提交,填写项目 URL、分类、描述和安装方式等信息即可。表单提交后会自动路由:
needs-metadata:必填字段、URL 或分类路由还需补充信息;duplicate:该项目 URL 已存在于目录中;ready-for-pr:自动化已生成草稿 PR,等待维护者审核;automation-blocked:自动化生成了分支,但 PR 创建被权限阻止。
当表单信息足够完整时,自动化会直接帮你起草包含 Markdown 条目和元数据侧车的 PR,你几乎不用手写代码。 ✅
方式三:通过社区清理队列间接贡献
不想加新服务器?可以修复已有条目的问题,详见下文"从清理队列开始"。
写好一个条目:5 个关键元数据字段
条目很简单也能被收录,但元数据越完整,服务器对 AI Agent 和用户越有用。高质量的条目应能回答这些问题(参考 docs/index-alpha/contribution-guide.md):
- Install(安装):
npx、uvx、pip、Docker 还是远程端点? - Transport(传输方式):
stdio、sse还是streamable-http? - Auth(认证):无需认证、API key、OAuth 还是 bearer token?
- Clients(支持客户端):Claude Desktop、Cursor、Codex、VS Code 等?
- Docs / License / Tools:文档地址、开源协议、工具数量和关键工具名?
对于简短的 Markdown 条目,这些结构化信息可以放在 data/server-metadata/{serverId}.json 侧车文件中,让分类页保持简洁的同时,Profile 和 API 依然拿到完整字段。字段格式以 schemas/server-metadata.schema.json 为准。
认领(Claim)你的服务器 Profile
如果你本身就是某个 MCP 服务器的维护者,合并条目后还可以进一步操作:
- 合并后获取资产:PR 合入
main后,后续评论会给出你的服务器公开 Profile 地址、API Profile 地址、安装配置链接和 README 徽章 Markdown; - 认领 Profile:通过仓库的 claim profile issue 表单提交认领,展示"社区维护者所有"的元数据(注意:认领状态不代表 TensorBlock 官方验证);
- 修正元数据:通过 improve metadata issue 表单,附上 Profile id 和结构化值(如
Install:、Transport:、Auth:、License:),自动化信息清晰时会直接起草元数据侧车 PR 供维护者审核; - 加徽章:把 MCP Index 徽章加到自己项目的 README,方便用户从你的仓库跳回索引 Profile。
低门槛起步:从社区清理队列开始
如果你只想做第一次贡献,清理队列是最佳入口:验证失效条目、修正元数据、调整分类、关闭重复项。队列详情见 docs/community-cleanup-queue.md,主要任务通道包括:
- Good first metadata:小的安装、文档、认证、传输、协议等元数据修复,最适合新手;
- Broken entries:死链、重复条目、失效项目、错误分类;
- Catalog health:定时健康检查自动发现的问题报告。
💡 领取任务前,先在 issue 中留言说明你正在处理,避免两人做同一件事;并检查该 URL 是否已在其他 docs/*.md 中出现。
合并前验证:本地跑一遍构建
如果你的改动涉及元数据侧车、生成器或 API,建议在本地按顺序执行以下命令(维护者验证流程,见 README.md):
npm run catalog:build
npm run profiles:build
npm test
npm run typecheck
npm run build
⚠️ 注意:data/catalog.json、data/catalog-errors.json 和 data/profiles/*.json 都是构建输出。除非维护者明确要求,否则清理 PR 中不要包含这些生成文件——只提交你对 docs/*.md 或 data/server-metadata/*.json 的修改即可。
常见问题速答
Q:不知道服务器属于哪个分类怎么办? A:使用 Add MCP server issue 表单提交,维护者会帮你路由到正确分类。
Q:我提交了条目,多久能上线?
A:PR 合入 main 后,部署工作流会重建目录与 Profile,托管 API 和公开 Profile 页面在部署成功后自动刷新。
Q:本地想体验索引能力?
A:运行 npm run registry:mcp 可启动本地 registry MCP 服务器(提供 search_servers、get_server_profile 等工具),API 接口说明见 docs/index-api.md。
写在最后
awesome-mcp-servers 的价值来自社区:无论是提交一个新的 MCP 服务器条目、认领自己的 Profile,还是顺手修一条死链,每一份贡献都在让这份 MCP 服务器目录更好用。建议新手从清理队列的 good first metadata 任务开始,熟悉流程后再尝试提交完整条目。祝你贡献顺利! 🎉