: The Fastest Way to Build MCP Servers

EZ-MCP：构建 MCP 服务的最快方式

不到 2 分钟即可启动 MCP 服务！ 此仓库包含完整、可直接运行的模板，用于构建单文件、自包含的 MCP 服务，支持 Python/uv 和 TypeScript/Deno。

🚀 为什么选择 EZ-MCP？

• ⚡ 即刻开始：复制、粘贴、运行，无需复杂配置
• 🎯 可用于生产环境：两个模板都使用官方 Anthropic SDK
• 📚 丰富示例：所有内容都有文档说明和可运行的代码
• 🔧 易于扩展：几分钟即可添加自己的工具、资源和提示词
• 💡 非常适合试验：在本地测试 MCP 想法的最快方式

📁 你将获得什么

两个功能完全相同、经过实战验证的模板：

• ez-mcp.py - 使用官方 MCP SDK 和 UV 的 Python 服务
• ez-mcp.ts - 使用官方 MCP SDK 和 Deno 的 TypeScript 服务

每个模板都演示了 MCP 的所有核心功能：

• 📊 资源：为大模型上下文提供动态数据源
• 🛠️ 工具：大模型可调用以执行操作的函数
• 📝 提示词：可在大模型交互中重复使用的模板
• ⚙️ 配置：支持环境变量

⚡ 快速体验

想看看这些服务的运行效果吗？选择你的语言并运行：

Python 版本

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and run immediately
git clone <this-repo>
cd ez-mcp
uv run ez-mcp.py

TypeScript 版本

# Install Deno (if not already installed)
curl -fsSL https://deno.land/install.sh | sh

# Clone and run immediately
git clone <this-repo>
cd ez-mcp
deno run --allow-all ez-mcp.ts

两个服务都会立即启动，并显示可用内容！

🎯 创建自己的服务（复制并自定义，只需 5 分钟）

构建自己的 MCP 服务，最快的方法是复制我们的一个模板并进行自定义。两个模板的功能完全相同，且可用于生产环境——只需选择你偏好的语言！

Python 开发者：

1. 复制模板：

   curl -O https://raw.githubusercontent.com/your-repo/ez-mcp/main/ez-mcp.py
   # Or just copy the ez-mcp.py file contents from this repo
   

2. 重命名并自定义：

   cp ez-mcp.py my-awesome-server.py
   

3. 编辑服务详情（大约在第 160 行）：

   mcp = FastMCP(
       name="My Awesome Server",  # <- Change this to your server name
       dependencies=["mcp>=1.9.0"]
   )
   

4. 添加自己的工具（在文件任意位置复制此模式）：

   @mcp.tool()
   def my_custom_tool(input_text: str) -> str:
       """Describe what your tool does"""
       # Your logic here
       return f"Processed: {input_text}"
   

5. 运行你的服务：

   uv run my-awesome-server.py
   

TypeScript/JavaScript 开发者：

1. 复制模板：

   curl -O https://raw.githubusercontent.com/your-repo/ez-mcp/main/ez-mcp.ts
   # Or just copy the ez-mcp.ts file contents from this repo
   

2. 重命名并自定义：

   cp ez-mcp.ts my-awesome-server.ts
   chmod +x my-awesome-server.ts
   

3. 编辑服务详情（大约在第 160 行）：

   const server = new McpServer({
     name: "My Awesome Server",  // <- Change this to your server name
     version: "1.0.0"
   });
   

4. 添加自己的工具（在文件任意位置复制此模式）：

   server.tool(
     "my-custom-tool",
     { input_text: z.string() },
     async ({ input_text }) => ({
       content: [{ type: "text", text: `Processed: ${input_text}` }]
     })
   );
   

5. 运行你的服务：

   deno run --allow-all my-awesome-server.ts
   

🎉 就这么简单！

现在你已经拥有一个可用的 MCP 服务！模板包含丰富的行内文档和示例，介绍如何添加：

• 数据库连接（SQLite、PostgreSQL 等）
• API 集成（REST API、GraphQL 等）
• 文件操作（读取、写入、搜索）
• 网页抓取
• 环境变量和配置
• 错误处理和验证

只需阅读模板代码——它旨在教会你所需的一切！

� 连接到 MCP 客户端

服务运行后，即可将其连接到任何 MCP 客户端：

MCP 客户端配置

添加到你的 mcp.json 文件中：

Python 服务

{
  "mcpServers": {
    "my-python-server": {
      "command": "uv",
      "args": ["run", "/absolute/path/to/your-server.py"],
      "env": {
        "MY_API_KEY": "your-key-here"
      }
    }
  }
}

TypeScript 服务

{
  "mcpServers": {
    "my-typescript-server": {
      "command": "deno", 
      "args": ["run", "--allow-all", "/absolute/path/to/your-server.ts"],
      "env": {
        "MY_API_KEY": "your-key-here"
      }
    }
  }
}

🛠️ 开发与测试

使用 MCP Inspector 进行开发

MCP Inspector 提供了一个 Web 界面，可用于测试你的服务：

Python

# Install the inspector
pip install mcp

# Run with inspector
uv run mcp dev your-server.py

TypeScript

# Install the inspector
npm install -g @modelcontextprotocol/inspector

# Run with inspector  
npx @modelcontextprotocol/inspector deno run --allow-all your-server.ts

这会打开一个 Web 界面，你可以在其中：

• 🔍 浏览可用的工具、资源和提示词
• ▶️ 使用不同参数测试工具
• 📖 查看资源内容
• 🧪 试用提示词

添加依赖

Python

编辑 .py 文件顶部的依赖部分：

# dependencies = [
#   "mcp>=1.9.0",
#   "requests",     # For HTTP requests
#   "pandas",       # For data manipulation  
#   "sqlalchemy",   # For database access
# ]

TypeScript

只需导入所需内容——其余工作由 Deno 处理：

import { parse } from "https://deno.land/[email protected]/csv/mod.ts";
import { serve } from "https://deno.land/[email protected]/http/server.ts";
import { DB } from "https://deno.land/x/[email protected]/mod.ts";

💡 实际示例

快速文件搜索工具

# Python
@mcp.tool()
def search_files(pattern: str, directory: str = ".") -> str:
    """Search for files matching a pattern"""
    import glob
    import os
    matches = glob.glob(os.path.join(directory, f"**/*{pattern}*"), recursive=True)
    return f"Found {len(matches)} files: {matches[:10]}"  # Show first 10

// TypeScript  
server.tool(
  "search-files",
  { pattern: z.string(), directory: z.string().default(".") },
  async ({ pattern, directory }) => {
    const matches = [];
    for await (const entry of Deno.readDir(directory)) {
      if (entry.name.includes(pattern)) {
        matches.push(entry.name);
      }
    }
    return {
      content: [{ type: "text", text: `Found files: ${matches.join(", ")}` }]
    };
  }
);

网页抓取工具

# Python (add "requests" to dependencies)
@mcp.tool()
async def scrape_url(url: str) -> str:
    """Scrape text content from a URL"""
    import httpx
    async with httpx.AsyncClient() as client:
        response = await client.get(url)
        return response.text[:1000]  # First 1000 chars

// TypeScript
server.tool(
  "scrape-url", 
  { url: z.string() },
  async ({ url }) => {
    const response = await fetch(url);
    const text = await response.text();
    return {
      content: [{ type: "text", text: text.slice(0, 1000) }]
    };
  }
);

数据库查询工具

# Python (add "sqlite3" - built-in)
@mcp.tool()
def query_db(sql: str) -> str:
    """Execute a SQL query"""
    import sqlite3
    conn = sqlite3.connect("data.db")
    results = conn.execute(sql).fetchall()
    conn.close()
    return str(results)

// TypeScript
import { DB } from "https://deno.land/x/[email protected]/mod.ts";

const db = new DB("data.db");

server.tool(
  "query-db",
  { sql: z.string() },
  async ({ sql }) => {
    const results = db.queryEntries(sql);
    return {
      content: [{ type: "text", text: JSON.stringify(results, null, 2) }]
    };
  }
);

🏗️ 模板功能说明

两个模板都包含相同的功能，用于演示 MCP 的所有能力：

📊 资源（数据源）

• server://info - 动态服务信息
• 展示如何创建大模型可访问的数据源
• 非常适合用于配置、文档或实时数据

🛠️ 工具（LLM 函数）

• hello_someone（Python）/ hello-someone（TypeScript）
• 演示参数验证和环境变量
• 可作为模板，用于创建任何希望大模型调用的函数

📝 提示词（模板）

• greeting_prompt（Python）/ greeting-prompt（TypeScript）
• 展示如何创建可重复使用的提示词模板
• 非常适合复杂指令或工作流

⚙️ 配置

• 支持环境变量（GREETING_PREFIX）
• 错误处理和输入验证
• 可用于生产环境的日志记录和启动消息

� 常见用例

非常适合：

• 🧪 快速原型开发：几分钟内测试 MCP 创意
• 🔧 个人自动化：为日常任务编写快捷脚本
• 📊 数据访问：将大模型连接到数据库/API
• 🌐 Web 集成：抓取网站、调用 API、处理数据
• 📁 文件操作：搜索、读取、写入和整理文件
• 🔍 开发工具：代码分析、文档编写、测试
• 💼 业务逻辑：自定义工作流和集成

📚 了解更多并获取帮助

核心资源

• 📖 MCP 规范：https://modelcontextprotocol.io/
• 🐍 Python SDK 文档：https://github.com/modelcontextprotocol/python-sdk
• 📜 TypeScript SDK 文档：https://github.com/modelcontextprotocol/typescript-sdk
• � MCP 社区：参与讨论并获取帮助

深入了解代码

两个模板文件都包含详尽的内联文档，其中包括：

• 逐行说明
• 高级用法模式
• 集成示例（数据库、API、文件系统）
• 错误处理最佳实践
• 性能优化技巧
• 生产环境部署指南

阅读源代码——它旨在帮助你掌握所需的一切知识！

🤝 贡献与反馈

觉得这些模板很有帮助？对改进有想法？欢迎告诉我们！

• 🐛 报告问题或提出功能建议
• 📝 分享你创建的精彩 MCP 服务
• 🔧 提交模板改进
• 📚 帮助完善文档

📜 许可证

MIT License——随意使用这些模板！详情请参阅 LICENSE 文件。

© Eleanor Berger — ai.intellectronica.net