microsoft/mcp-for-beginners · 上手攻略

仓库：microsoft/mcp-for-beginners
链接：https://github.com/microsoft/mcp-for-beginners
分类：skill / agent（MCP 入门教程）
作者：spark
更新：2026-07-13

一、是什么

microsoft/mcp-for-beginners 是微软出品的 Model Context Protocol（MCP）官方入门课程仓库。MCP 是由 Anthropic 在 2024-11 提出的开放协议，用来标准化"LLM 应用 ↔ 工具 / 数据源"之间的连接方式（你可以把它类比为 AI 时代的"USB-C"）。

这个仓库不是 SDK、不是运行时，而是结构化课程 + 跨语言代码示例，覆盖：

协议基础概念（Resources / Prompts / Tools / Sampling）
安全模型与最佳实践
用 C# / Java / TypeScript / JavaScript / Rust / Python 六种主流语言实现 MCP Server & Client
VS Code、Claude Desktop、Cursor、Cline 等 host 集成
Azure 上的生产部署
13 个 lab 的 PostgreSQL 综合实战（Module 11）
50+ 语言翻译（含简体中文 translations/zh-CN/）

课程对齐 MCP Specification 2025-11-25（Latest Stable），并预告下一版 Release Candidate 2026-07-28（按日期化版本号）。截至 2026-07，仓库约 16.7k Stars、周增 +28，是 MCP 生态最权威的中文友好入门材料。

二、解决什么问题

MCP 解决的是 LLM 应用的两个核心痛点：

N×M 集成困境：每个 LLM 框架（LangChain、Semantic Kernel、Claude SDK…）要连每个工具（数据库、GitHub、Jira、Slack…），都是一套定制适配。MCP 提供"Server-Client"标准协议，让任意 LLM 客户端能即插即用任意 MCP Server。
上下文传递混乱：以往工具调用 / 多轮对话的上下文传递各凭本事，MCP 统一了 JSON-RPC 2.0 的消息格式、Resources（数据）、Prompts（提示模板）、Tools（可调用函数）三大原语。

而本仓库解决的是学习曲线陡峭：MCP 协议虽然简洁，但官方 spec 是规范文档而非教程，新手往往不知道从哪个 SDK、哪个 IDE、哪个 host 开始动手。微软这份课程把"最小可行例子"拆成 10+ 章节，配可运行代码。

三、快速安装

课程主体是 Markdown，不需要"安装"，但要做 lab 必须装对应 SDK。建议 Python ≥ 3.10 + Node ≥ 18。

3.1 拉代码（避免 50+ 翻译拖慢速度）

# 推荐 sparse checkout，跳过翻译目录
git clone --filter=blob:none --sparse https://github.com/microsoft/mcp-for-beginners.git
cd mcp-for-beginners
git sparse-checkout set --no-cone '/*' '!translations' '!translated_images'

3.2 Python SDK（MCP 官方）

pip install "mcp[cli]"
# 或装最新开发版
pip install git+https://github.com/modelcontextprotocol/python-sdk.git

3.3 TypeScript SDK

npm install @modelcontextprotocol/sdk

3.4 C# / Java / Rust SDK

语言	包
C#	`ModelContextProtocol`（NuGet，预览版）
Java	`io.modelcontextprotocol:mcp-sdk`（Maven Central）
Rust	`mcp-sdk` crate（GitHub: modelcontextprotocol/rust-sdk）

⚠️ 坑：仓库结构按"00-Introduction / 01-CoreConcepts / … / 11-…lab"组织，建议从 Module 0 顺读；不要直接跳到 Module 11 的 lab，缺前置概念会懵。

四、核心用法

4.1 最小 MCP Server（Python 示例，对应 `03-GettingStarted/01-first-server`）

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

mcp = FastMCP("weather")

@mcp.tool()
def get_forecast(city: str, days: int = 3) -> str:
    """返回城市的未来 N 天天气预报（这里用占位实现）"""
    return f"{city} 未来 {days} 天：晴，最高 28°C，最低 18°C"

if __name__ == "__main__":
    # stdio 传输，适合本地进程内嵌
    mcp.run(transport="stdio")

启动后用一个 MCP Inspector 或任意 host（比如 Claude Desktop）连接，就能让 LLM 调用 get_forecast 工具。

4.2 最小 MCP Client（对应 `03-GettingStarted/02-client`）

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

async def main():
    params = StdioServerParameters(
        command="python", args=["weather_server.py"]
    )
    async with stdio_client(params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            tools = await session.list_tools()
            print([t.name for t in tools.tools])
            result = await session.call_tool("get_forecast", {"city": "上海"})
            print(result.content)

asyncio.run(main())

4.3 在 VS Code 里消费 MCP Server（对应 `03-GettingStarted/04-vscode`）

在 .vscode/mcp.json 注册：

{
  "servers": {
    "weather": {
      "type": "stdio",
      "command": "python",
      "args": ["${workspaceFolder}/weather_server.py"]
    }
  }
}

打开 Copilot Chat，输入 /tools 就能看到 weather server 暴露的 get_forecast。

4.4 接入主流 MCP Host（对应 `03-GettingStarted/12-mcp-hosts`）

Host	配置文件
Claude Desktop	`~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）
Cursor	`~/.cursor/mcp.json`
Cline (VS Code)	`.vscode/cline_mcp_settings.json`
Continue	`~/.continue/config.json`

格式统一是 {"mcpServers": {...}} JSON。

4.5 HTTP 流式传输（对应 `03-GettingStarted/06-http-streaming`）

把 transport 换成 streamable-http：

mcp.run(transport="streamable-http", host="127.0.0.1", port=8000, path="/mcp")

适合跨机器、跨进程部署；注意加上 TLS 和 OAuth2（见 Module 5.3）。

4.6 调试：用 MCP Inspector（对应 `03-GettingStarted/13-mcp-inspector`）

npx @modelcontextprotocol/inspector python weather_server.py

可视化地列出 tools / resources / prompts，直接在浏览器里手动调用。

五、典型适用场景

AI Agent 工程师：要从零搭一套"LLM + 工具调用"系统，本课程是 MCP 世界的"hello world"。
企业内部工具接入：希望 ChatGPT / Claude / Copilot 都能用自家 Jira、Confluence、DB，自研 MCP Server 一次接所有 host。
协议研究者：MCP 演进很快，本仓库有完整的版本变更解释（特别是 2026-07-28 RC 的无状态传输、Extensions 框架、Roots/Sampling/Logging 弃用说明）。
教学：12 模块 + lab，可作为高校或企业培训 MCP 的标准教材。

六、坑与注意

spec 与课程版本漂移：本课程基于 2025-11-25（latest stable），2026-07-28 RC 中 Roots、Sampling、Logging 被弃用。如果你看 spec 旧版示例，会发现这些概念；新版中不要再依赖它们。
协议是 JSON-RPC 2.0：2025-11-25 移除了 batching 支持，老示例里 batch: true 已经无效。
OAuth2 不能跳过：生产环境的 MCP Server 一律走 OAuth2 + 用户授权（Module 5.3），不要把 API key 写死到 server。
stdio vs HTTP：本地进程内嵌用 stdio；跨机器才用 streamable-http。stdio 千万别暴露到公网。
Transport 层无状态（2026-07-28 RC 起的预期变化）：课程里有些示例假设 server 保留 session state，未来 RC 落地后这部分会改——以 Module 1.1 "What's Changing in MCP" 章节为准。
C# SDK 还是预览版：API 在 1.0 前会变，生产项目锁版本号。
仓库里有 50+ 翻译目录：完整 clone 会占 1GB+ 空间，务必用 sparse checkout。
Module 11 的 PostgreSQL lab：默认假设你已经装好 PG；macOS 用 brew install postgresql@16，Windows 用 Docker，不要直接走本地默认端口。

七、与同类对比

资源	形式	优势	短板
microsoft/mcp-for-beginners（本）	课程 + 多语言示例	结构化、跨语言、微软维护、持续跟进 spec	偏新手，进阶内容不如 spec 详细
modelcontextprotocol/specification	规范文档	权威、完整、含 SEP 提案	不友好、需要啃
modelcontextprotocol/inspector	调试工具	可视化测试 tools/resources	不是学习材料
awesome-mcp-servers	服务器清单	找现成 server	没有教程
LangChain / LlamaIndex 自带 tool 抽象	框架原生	集成简单	协议私有，不能跨框架复用
OpenAI Function Calling	闭源协议	ChatGPT 生态最优	不是开放协议，锁定生态

一句话：要"按图索骥地学会 MCP"，从这份仓库开始；要"权威定义"去 spec；要"现成工具"去 awesome 列表。

八、一句话推荐结论

这是 2026 年学习 MCP 最友好、最权威、最跟得上 spec 演进的中文友好入门材料：12 个模块、六种主流语言、可直接 sparse checkout 拉到本地，配合 MCP Inspector 当作练兵场，2-3 天就能从零搭出可被 Claude / Cursor / Copilot 调用的 MCP Server；唯一要注意的是它对齐的是 2025-11-25 spec 而不是即将到来的 2026-07-28 RC，长期项目盯紧 SEP 提案。