2026年MCP服务器搭建教程：创建你自己的AI工具接口

MCP（Model Context Protocol）是连接AI模型和外部工具的标准协议。本文从零开始，使用Python SDK手把手教你搭建自己的MCP服务器，定义工具、暴露资源、集成客户端，让你的AI应用能够连接任意外部系统。

5 分钟阅读
提效录
#AI Agent #AI #AI编程
2026年MCP服务器搭建教程：创建你自己的AI工具接口

MCP（Model Context Protocol）是Anthropic于2024年底提出的开放标准协议，目标是解决AI模型与外部工具和数据源之间的标准化连接问题。到了2026年，MCP已经成为AI工具集成的事实标准。

为什么需要MCP

在MCP出现之前，每个AI应用要连接外部工具，都需要编写专门的适配代码。比如连接GitHub需要一套代码，连接Slack又需要另一套代码。MCP通过定义统一的协议标准，实现了”一次开发，处处连接”。

MCP的核心架构

MCP采用客户端-服务器架构：

  • MCP Host（宿主）：AI应用程序，如Claude Desktop、Cursor等
  • MCP Client（客户端）：宿主中负责与服务器通信的组件
  • MCP Server（服务器）：你开发的工具接口，暴露特定功能给AI

MCP服务器可以提供三种能力：

  1. Tools（工具）：AI可以调用的函数（如搜索、计算、API调用）
  2. Resources（资源）：AI可以读取的数据（如文件、数据库记录）
  3. Prompts（提示）：预定义的交互模板

更多关于MCP协议的基础知识，可以参考MCP协议入门教程和MCP完全指南。

二、Python SDK安装与环境配置

MCP官方提供了Python和TypeScript两种SDK。本文使用Python SDK进行开发。

环境准备

# 创建虚拟环境
python -m venv mcp-env
source mcp-env/bin/activate  # Windows: mcp-env\Scripts\activate

# 安装MCP SDK
pip install mcp[cli]

# 验证安装
mcp --version

项目结构

建议按以下结构组织项目：

my-mcp-server/
├── server.py          # 主服务器文件
├── tools/             # 工具定义
│   ├── __init__.py
│   ├── search.py
│   └── calculator.py
├── resources/         # 资源定义
│   ├── __init__.py
│   └── data.py
├── requirements.txt
└── mcp_config.json    # 客户端配置

三、创建基础MCP服务器

让我们从一个最简单的MCP服务器开始，然后逐步添加功能。

最小可运行服务器

# server.py
from mcp.server.fastmcp import FastMCP

# 创建MCP服务器实例
mcp = FastMCP("my-first-server")

@mcp.tool()
def hello(name: str) -> str:
    """向用户打招呼"""
    return f"你好，{name}！欢迎使用MCP服务器。"

@mcp.tool()
def add(a: int, b: int) -> int:
    """计算两个数的和"""
    return a + b

if __name__ == "__main__":
    mcp.run(transport="stdio")

运行与测试

使用MCP Inspector进行测试：

# 安装Inspector
npx @modelcontextprotocol/inspector python server.py

Inspector会在浏览器中打开一个调试界面，你可以看到所有注册的工具，并手动调用它们查看返回结果。

在Claude Desktop中配置

编辑Claude Desktop的配置文件：

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["/path/to/server.py"]
    }
  }
}

重启Claude Desktop后，AI就能自动发现并使用你定义的工具了。

四、工具定义详解

工具（Tools）是MCP服务器最核心的能力。一个好的工具定义能让AI准确地理解何时以及如何使用它。

工具参数与类型

from mcp.server.fastmcp import FastMCP
from pydantic import BaseModel, Field
from typing import Optional

mcp = FastMCP("advanced-tools-server")

class SearchParams(BaseModel):
    query: str = Field(description="搜索关键词")
    max_results: int = Field(default=10, description="最大结果数量")
    category: Optional[str] = Field(default=None, description="搜索类别")

@mcp.tool()
def search_documents(params: SearchParams) -> str:
    """搜索文档库中的内容。
    
    当用户需要查找特定信息、文档或资料时使用此工具。
    支持关键词搜索和类别过滤。
    """
    # 实际实现中调用搜索引擎
    results = document_search(
        query=params.query,
        max_results=params.max_results,
        category=params.category
    )
    return format_results(results)

错误处理最佳实践

@mcp.tool()
def fetch_url(url: str) -> str:
    """获取指定URL的网页内容"""
    try:
        import httpx
        async with httpx.AsyncClient() as client:
            response = await client.get(url, timeout=10)
            response.raise_for_status()
            return response.text[:5000]  # 限制返回长度
    except httpx.TimeoutException:
        return "错误：请求超时，请检查URL是否正确"
    except httpx.HTTPStatusError as e:
        return f"错误：HTTP {e.response.status_code}，无法访问该页面"
    except Exception as e:
        return f"错误：{str(e)}"

工具描述的重要性

工具的描述（docstring）是AI决定是否调用该工具的关键依据。好的描述应该包含：

  1. 做什么：工具的功能说明
  2. 何时用：什么情况下应该使用这个工具
  3. 参数说明：每个参数的含义和格式要求
  4. 返回值：返回结果的格式和内容

五、资源暴露（Resources）

资源（Resources）让AI能够读取特定的数据，与工具的区别在于资源是只读的、被动提供的数据。

定义静态资源

@mcp.resource("config://app-settings")
def get_app_settings() -> str:
    """获取应用配置信息"""
    return json.dumps({
        "version": "2.0.0",
        "features": ["search", "analytics", "export"],
        "limits": {"max_queries": 1000, "max_file_size": "10MB"}
    })

定义动态资源

@mcp.resource("data://users/{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    """获取指定用户的个人信息"""
    # 从数据库查询用户信息
    user = db.query("SELECT * FROM users WHERE id = ?", user_id)
    if not user:
        return "用户不存在"
    return json.dumps({
        "name": user.name,
        "email": user.email,
        "role": user.role
    })

资源模板

资源模板允许使用URI参数来动态生成资源内容，非常适合数据库查询类场景：

@mcp.resource("db://table/{table_name}/row/{row_id}")
def get_database_row(table_name: str, row_id: str) -> str:
    """从数据库获取指定行数据"""
    allowed_tables = ["users", "orders", "products"]
    if table_name not in allowed_tables:
        return f"不支持的表名：{table_name}"
    
    row = db.fetch_one(f"SELECT * FROM {table_name} WHERE id = ?", row_id)
    return json.dumps(row) if row else "记录不存在"

六、客户端集成

开发完MCP服务器后，需要让各种AI客户端能够连接到它。

与Claude Desktop集成

编辑配置文件 ~/Library/Application Support/Claude/claude_desktop_config.json（macOS）或 %APPDATA%\Claude\claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "my-server": {
      "command": "python",
      "args": ["/path/to/server.py"],
      "env": {
        "API_KEY": "your-api-key",
        "DATABASE_URL": "sqlite:///data.db"
      }
    }
  }
}

与Cursor集成

在Cursor设置中添加MCP服务器配置：

{
  "mcp": {
    "servers": {
      "my-server": {
        "command": "python",
        "args": ["/path/to/server.py"]
      }
    }
  }
}

编程方式集成

如果你开发自己的AI应用，可以用MCP客户端SDK连接服务器：

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(
        command="python",
        args=["server.py"]
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # 列出可用工具
            tools = await session.list_tools()
            print(f"可用工具: {[t.name for t in tools.tools]}")
            
            # 调用工具
            result = await session.call_tool(
                "search_documents",
                arguments={"query": "MCP协议", "max_results": 5}
            )
            print(result.content[0].text)

七、MCP与Function Calling对比

很多开发者会问：MCP和OpenAI的Function Calling有什么区别？

核心差异

维度MCPFunction Calling
架构客户端-服务器分离集成在API请求中
标准化开放标准协议供应商专有
工具发现自动发现（服务器声明）手动定义（每次请求传入）
跨平台支持多种AI客户端仅限特定模型API
持久化服务器长期运行无状态，每次请求重新定义
资源支持支持资源和提示模板仅支持函数调用
安全隔离独立进程运行运行在应用进程中

何时用MCP，何时用Function Calling

用MCP的场景：

  • 需要跨多个AI客户端共享同一套工具
  • 工具需要维护状态（如数据库连接、会话）
  • 需要暴露数据资源而不仅仅是函数
  • 追求工具代码的复用性和可维护性

用Function Calling的场景：

  • 简单的单次工具调用
  • 工具逻辑与业务紧密耦合
  • 不需要跨平台共享
  • 追求最低延迟（无进程间通信开销）

八、常见问题解答（FAQ）

Q：MCP服务器支持哪些传输方式？

A：目前MCP支持两种传输方式：1) stdio（标准输入输出）——服务器作为子进程运行，通过stdin/stdout通信，适合本地部署；2) SSE（Server-Sent Events）——通过HTTP传输，适合远程部署和多客户端共享场景。2026年最新的Streamable HTTP传输也在逐步推广中。

Q：如何保证MCP服务器的安全性？

A：几个关键措施：1) 不要在服务器代码中硬编码敏感信息，使用环境变量；2) 对工具参数做严格的类型校验和边界检查；3) 限制资源的访问范围（如只允许查询特定表）；4) 使用OAuth 2.1进行远程服务器的身份认证；5) 记录所有工具调用的日志，便于审计。

Q：MCP服务器能用TypeScript开发吗？

A：完全可以。MCP官方同时提供Python和TypeScript SDK。TypeScript版本使用@modelcontextprotocol/sdk包，API设计与Python版本类似。选择哪种语言取决于你的技术栈偏好——如果你的AI应用是Node.js生态，用TypeScript更方便集成。

Q：一个MCP服务器可以暴露多少个工具？

A：技术上没有限制，但建议每个服务器的工具数量控制在10-20个以内。过多的工具会让AI在选择时产生困惑，降低调用准确率。如果功能较多，建议拆分为多个专门的MCP服务器（如搜索服务器、数据库服务器、API服务器），每个服务器职责单一。

总结

MCP协议为AI工具集成提供了优雅而强大的标准化方案。通过本文的实战教程，你已经掌握了从创建基础服务器到定义复杂工具、从暴露数据资源到客户端集成的完整开发流程。

在实际项目中，建议遵循”小而专”的原则——每个MCP服务器专注于一个领域，提供精炼的工具集。这样不仅便于维护，也能让AI更准确地选择和使用工具。更多关于AI开发的技术文章，可以参考AI工具合集2026。

分享文章：

常见问题

MCP服务器搭建教程创建你自己零基础能学会吗？
完全可以。文中从零开始逐步讲解，配有详细截图和操作步骤，新手也能轻松跟上。
学MCP服务器搭建教程创建你自己需要花钱吗？
核心功能大多免费，部分高级功能需要订阅，文中标注了每项功能的免费和付费情况。
学完MCP服务器搭建教程创建你自己能达到什么水平？
学完可以独立完成实际项目，文中包含实战案例和进阶建议，帮你从入门到熟练。

相关文章

AI编程

别再手动改了！2026年AI做代码重构终极指南，让你的屎山代码脱胎换骨

6月16日

AI编程

2026年彻底改变开发效率：AI写JavaScript代码终极实战指南

6月16日

AI编程

独家揭秘2026：ai编程用什么语言？选错方向可能让你白白浪费半年！

6月16日