Claude MCP Server Builder

Claude Desktop的MCP服务器构建器

使用全面的系统提示和测试驱动的工作流程为Claude Desktop构建生产就绪的MCP服务器

此存储库提供了全面的系统说明，使Claude（或支持项目方法的任何LLM）能够指导您构建以代理为中心的设计和可选令牌优化的生产就绪MCP服务器。

✨ 特性

• 🎯 以代理为中心的设计 -面向工作流的工具，最大限度地减少了Claude的编排负担
• 🧪 测试驱动开发 -在构建MCP服务器之前验证API
• ⚡ FastMCP优先 -90%的用例使用最快的路径
• 📁 扁平结构 -简单的项目布局，可根据需要进行扩展
• 🔄 局部测试 -没有Claude Desktop重启的测试工具
• ⚡ 令牌优化 -工作流服务器的可选模式（减少90-99%）
• 📊 代币透明度 -优化服务器的自我报告
• 📚 生产模式 -基于具有50多种生产工具的真实服务器
• 🎯 分步指导 -克劳德带你走过每一个阶段

🚀 快速开始

让您的第一台MCP服务器在中运行 2-4小时:

1. 创建克劳德项目 （2分钟）

   Open Claude.ai → Projects → Create Project → "MCP Server Builder"

1. 添加系统说明 （2分钟）

- 复制 docs/SYSTEM_INSTRUCTIONS.md - 粘贴到项目的“自定义说明”中 - 保存

1. 开始建立 （1分钟）

   I want to build an MCP server for [YOUR_SERVICE].

   Service details:
   - Type: [REST API / Database / SaaS]
   - Authentication: [API key / OAuth / etc]
   - Key operations: [list 3-5 things]
   - Usage pattern: [How often will this be called?]

   Let's start with test_client.py.

就是这样！克劳德将指导您完成其余部分。

👉 完整快速入门指南→

📋 所得

核心文件

模板和工具

• 模板/ -MCP项目的入门文件
• 包括： .env.example, .gitignore, requirements.txt，项目快速入门模板

🎯 工作流程

┌─────────────────┐
│  test_client.py │  ← Test API authentication & operations
└────────┬────────┘
         │ ✅ Pass
         ▼
┌─────────────────┐
│   Build Server  │  ← Create MCP server with agent-centric tools
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  test_server.py │  ← Test MCP tools locally
└────────┬────────┘
         │ ✅ Pass
         ▼
┌─────────────────┐
│test_token_usage │  ← Optional: Measure tokens (workflow servers)
└────────┬────────┘
         │ ✅ Pass
         ▼
┌─────────────────┐
│ Claude Desktop  │  ← Full integration
└─────────────────┘

关键原则：

• 永远不要构建你没有测试过的东西
• 为工作流而设计，而不是为API端点而设计
• 重要时进行优化（工作流服务器）

💡 设计理念

代理中心与API-中心

❌ API-中心（避免）：

list_databases()
list_schemas(database)
list_tables(database, schema)
# User: "What's in my warehouse?" → 10-50+ tool calls

✅ 以代理为中心（构建此）：

discover_data_warehouse(resource_type, search_term, filters)
# User: "What's in my warehouse?" → 1 tool call

何时进行优化

标准方法：

• 简单的单API包装器
• 不常使用（\10次通话/对话）
• 大量响应（>5000个令牌）
• 提出效率要求

系统说明指导您何时应用每种方法。

🎓 用例

为以下对象构建MCP服务器：

REST API

• 数据平台：Fivetran、人口普查、dbt Cloud、Hightouch
• 数据仓库：雪花、Rancher、BigQuery
• 云服务：AWS、GCP、Azure
• 工作流程：Jira，线性，Asana，周一
• 沟通：Slack、Twilio、SendGrid
• 自定义API：您的内部服务

数据库

• PostgreSQL、MySQL、Snowflake、BigQuery、MongoDB
• 使用以代理为中心的查询工具

SaaS平台

• GitHub、GitLab、Bitbucket
• 谷歌工作区，微软365
• 概念、汇流、SharePoint

工作流服务器

• 管道健康监测器
• 跨部门协调人
• 多阶段数据工作流程
• （内置令牌优化功能）

🎓 示例：构建天气MCP服务器

You: I want to build an MCP server for OpenWeatherMap API.

Service details:
- Type: REST API
- Authentication: API key
- Key operations:
  1. Get current weather
  2. Get 5-day forecast
  3. Search cities
- Usage: Checking weather 5-10 times per conversation

Let's start with test_client.py.

Claude: [Creates test_client.py with OpenWeatherMap API...]
        [Guides through agent-centric tool design...]
        [Consolidates related operations...]

结果： 在2-3小时内使用MCP服务器：

• 3-5个以试剂为中心的工具（不是10+以API为中心的刀具）
• 正确的测试和错误处理
• 必要时可选择优化

🏗️ 是什么让这与众不同

传统方法❌

1. 立即开始编码
2. 将每个API端点包装为工具
3. 与路径和配置作斗争
4. 在Claude Desktop中调试（缓慢）
5. 用户需要10次以上的工具调用来完成简单的任务
6. 编写文档（已过时）
7. 意识到你需要重构

这种方法✅

1. 首先测试API(test_client.py)
2. 设计以代理为中心的工具（工作流，而非端点）
3. 增量构建（MVP→ 扩展）
4. 本地测试(test_server.py)
5. 用户通过1-2次工具调用完成任务
6. 配置克劳德桌面（一旦它工作）
7. 可选：优化和验证令牌使用
8. 成功后的文档

📊 测试原理

三相（或四相）测试

1. test_client.py -API验证

- 身份验证成功 - 进行实际的API调用 - 优雅地处理错误 - 测试完整和轻量级方法（如果优化）

1. test_server.py -工具验证

- 直接测试MCP工具 - 验证JSON响应 - 检查错误处理 - 验证工具整合工作 - 无需克劳德桌面

1. test_token_usage.py -令牌测量（可选，适用于工作流服务器）

- 衡量实际代币消费 - 验证优化声明 - 提供每个组件的细分 - 实现数据驱动决策

1. 克劳德桌面 -集成

- 完整的端到端测试 - 自然语言接口 - 生产验证 - 真实世界的工作流测试

🛠️ 技术栈

支持的语言

• python （建议使用FastMCP）
• Types/Node.js （官方MCP SDK）

关键依赖关系

• FastMCP-快速MCP服务器开发
• python dotenv-环境管理
• 请求/httpx-API通信

需求

• Python 3.10+或Node.js 18+
• 克劳德桌面
• 您正在集成的服务的API凭据

📚 文档

入门指南

1. 快速入门指南 -距离首次提示还有5分钟
2. 系统说明 -以代理为中心的模式的完整指南
3. 项目设置 -详细配置

参考

• 用户提示模板 -复制粘贴提示
• 模板目录 -初学者文件

外部资源

• MCP协议规范
• 克劳德桌面下载
• FastMCP文档

🗺️ 路线图

当前版本（v1.0）

• ✅ 完整的系统说明
• ✅ 以代理为中心的设计模式
• ✅ 测试驱动的工作流程
• ✅ FastMCP第一种方法
• ✅ 令牌优化模式（可选）
• ✅ 工作流服务器的令牌透明度
• ✅ 全面的文件

未来（待定）

📜 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 基于多个MCP服务器的模式构建
• 受到现实世界代币优化挑战的启发（实现了99%的减少）
• 由Claude和FastMCP提供技术支持
• 感谢模型上下文协议社区
• 感谢所有贡献者和早期采用者

🌟 成功案例

这种系统指令方法已被用于构建：

• 管道健康监测器 -98.9%的代币减少（37795→每张支票421个代币）
• 多服务编排器 -5个API，1个工具调用
• 数据平台探索者 -在1-2次通话中完成数据平台可见性

⭐ 表示支持

如果这个项目帮助你构建了更好的MCP服务器，那就给它一颗星吧！ ⭐

它帮助其他人发现这些模式，并鼓励持续发展。

______________________________________________________________________

准备好建造了吗？ 从 快速入门指南 →

问题？ 检查 文档