構建屬于自己的第一個 MCP 服務器：初學者教程

為什么需要 MCP 服務器？

你是否遇到過這樣的場景：向 AI 助手（比如 GitHub Copilot）詢問 “北京今天的天氣”，得到的回復卻是 “我無法訪問實時天氣數據”？

這是因為大多數 AI 模型本身 “與世隔絕”—— 它們只能依賴訓練時學到的知識，無法主動連接實時數據（如天氣 API）、操作工具（如瀏覽器）或調用外部服務（如 GitHub）。而模型上下文協議（MCP）服務器就是解決這個問題的 “橋梁”：它讓 AI 能像人一樣 “使用工具”，比如調用天氣 API 獲取實時數據、控制瀏覽器訪問網頁，甚至操作 GitHub 創建代碼提交。

舉個例子：

有了 Playwright MCP 服務器，AI 能自動打開瀏覽器，幫你測試網站功能；
有了 GitHub MCP 服務器，AI 能直接幫你創建代碼分支和拉取請求；
今天我們要做的 “天氣 MCP 服務器”，能讓 AI 隨時獲取全球任意城市的實時天氣 —— 從此問 AI 天氣，它能給你精準到溫度、濕度的答案。

什么是 MCP 服務器？

簡單說，MCP 服務器是 AI 與現實世界之間的 “翻譯官” 和 “工具管理員”。它的核心作用是：

告訴 AI “你有哪些工具可用”（比如 “天氣查詢工具”）；
接收 AI 的 “工具使用請求”（比如 “查上海的天氣”）；
調用實際的外部服務（比如天氣 API）獲取結果；
把結果整理后返回給 AI，讓 AI 能基于此生成回答。

有了 MCP 服務器，AI 不再是 “紙上談兵”，而是能真正 “動手” 解決需要實時數據或外部交互的問題。

本教程目標

我們將用 TypeScript 構建一個 “天氣 MCP 服務器”，實現：

讓 AI（如 GitHub Copilot）能通過這個服務器查詢任意城市的實時天氣；
掌握 MCP 服務器的核心開發流程，為后續開發其他工具（如股票查詢、新聞獲取）打基礎。

準備工作

在開始前，請確保你的環境滿足這些條件：

基本的 JavaScript/TypeScript 知識（能看懂簡單的變量、函數和異步代碼）；
電腦上安裝了 Node.js（推薦 v16 及以上，可通過node -v檢查版本，沒有的話去Node.js 官網下載）；
代碼編輯器（推薦 VS Code，方便后續與 GitHub Copilot 集成測試）；
網絡連接正常（需要下載依賴和調用天氣 API）。

步驟 1：項目初始化與環境配置

這一步我們要搭建基礎的項目結構，安裝必要的工具，讓代碼能正常運行。

1. 創建項目文件夾并進入

首先，打開終端（Windows 用 PowerShell 或命令提示符，Mac/Linux 用 Terminal），執行以下命令：

# 創建項目文件夾（名字可以自定義，這里用mcp-weather-server）
mkdir mcp-weather-server  
# 進入文件夾
cd mcp-weather-server

這一步的作用是：為項目創建一個獨立的文件夾，避免文件混亂。

2. 初始化 npm 項目

在終端中繼續執行：

npm init -y

作用：通過 npm（Node.js 的包管理工具）初始化項目，生成package.json文件（這個文件會記錄項目的基本信息和依賴）。
執行后，文件夾里會多出一個package.json，內容類似：

{"name": "mcp-weather-server","version": "1.0.0","main": "index.js","scripts": { "test": "echo \"Error: no test specified\" && exit 1" },"keywords": [],"author": "","license": "ISC","description": ""
}

3. 安裝必要的依賴

我們需要安裝 3 類工具：

MCP 服務器核心 SDK（@mcp/server）：用于快速搭建 MCP 服務器；
TypeScript 相關工具（typescript、@types/node、ts-node）：因為我們用 TypeScript 開發，需要編譯和運行 TS 代碼；

在終端執行：

npm install @mcp/server  
npm install typescript @types/node ts-node --save-dev

--save-dev表示這些工具是 “開發時依賴”（只在寫代碼時用，運行時不用）；
執行后，文件夾會多出node_modules（存放依賴代碼）和package-lock.json（記錄依賴的精確版本）。

4. 配置 TypeScript 編譯規則

TypeScript 需要通過tsconfig.json文件指定編譯規則（比如代碼編譯后生成的 JS 版本、是否嚴格檢查類型等）。

在終端執行：

npx tsc --init

npx是 npm 自帶的工具，用于臨時運行安裝的包；
執行后，文件夾會生成tsconfig.json，我們需要修改其中幾個關鍵配置（用 VS Code 打開文件，找到并修改）：

{"compilerOptions": {"target": "ES2020",  // 編譯后的JS兼容ES2020標準"module": "ESNext",  // 模塊系統用最新的ES模塊（與MCP SDK兼容）"moduleResolution": "NodeNext",  // 模塊查找規則匹配Node.js"outDir": "./dist",  // 編譯后的JS文件放在dist文件夾"rootDir": "./",     // 源代碼（TS文件）的根目錄"strict": true,      // 開啟嚴格類型檢查（減少錯誤）"esModuleInterop": true,  // 兼容CommonJS和ES模塊"skipLibCheck": true,    // 跳過對庫文件的類型檢查（加速編譯）"forceConsistentCasingInFileNames": true  // 文件名大小寫嚴格匹配}
}

這些配置的作用是：確保 TypeScript 代碼能正確編譯成 MCP SDK 支持的格式，避免運行時出錯。

5. 修改 package.json，啟用 ES 模塊

MCP SDK 使用的是現代 ES 模塊（即import/export語法），而 Node.js 默認用的是 CommonJS 模塊（require語法）。為了兼容，需要修改package.json：

用 VS Code 打開package.json，添加"type": "module"字段，修改后如下：

{"name": "mcp-weather-server","version": "1.0.0","type": "module",  // 新增：啟用ES模塊"main": "main.ts",  // 修改：入口文件為我們后續創建的main.ts"scripts": {"start": "ts-node main.ts",  // 新增：用ts-node直接運行main.ts"test": "echo \"Error: no test specified\" && exit 1"},"dependencies": {"@mcp/server": "^x.x.x"  // 版本號可能不同，以實際安裝為準},"devDependencies": {"@types/node": "^x.x.x","ts-node": "^x.x.x","typescript": "^x.x.x"}
}

新增的"start": "ts-node main.ts"讓我們可以用npm start直接運行 TypeScript 代碼（不用先編譯）；
"type": "module"確保 Node.js 用 ES 模塊語法解析代碼，避免出現import語法報錯。

6. 創建主文件

在項目文件夾中創建main.ts（這是我們的核心代碼文件）：

在 VS Code 中，右鍵項目文件夾 → “新建文件” → 命名為main.ts；
暫時不用寫內容，后續步驟會逐步填充。

步驟 2：安裝項目所需的依賴庫

在開始編寫代碼前，我們需要先安裝兩個核心工具庫，它們是搭建 MCP 服務器的 “基礎零件”。

1. 安裝 MCP SDK（核心開發工具）

MCP SDK（@modelcontextprotocol/sdk）是官方提供的開發包，里面包含了所有搭建 MCP 服務器的現成工具 —— 比如創建服務器實例、定義工具接口、處理 AI 與服務器的通信等。簡單說，有了它，我們不用從零寫代碼，直接用現成的功能就能快速搭起服務器框架。

安裝命令（在終端中執行）：

npm install @modelcontextprotocol/sdk

執行后，npm 會自動從網絡下載這個庫，并把它安裝到項目的node_modules文件夾里，同時在package.json的dependencies中記錄這個依賴（方便后續其他人運行項目時快速安裝）。

2. 安裝 Zod（數據驗證工具）

Zod（zod）是一個用于數據驗證的庫。它的作用是：確保 AI 發送給服務器的參數是 “合規” 的。比如我們的天氣服務器需要 “城市名” 作為參數，Zod 可以檢查 AI 是否真的傳了一個字符串（而不是數字或空值），如果參數不對，會直接報錯，避免服務器因為無效數據崩潰。

安裝命令（繼續在終端執行）：

npm install zod

檢查安裝結果

安裝完成后，打開項目中的package.json文件，在"dependencies"部分應該能看到這兩個庫的記錄（版本號可能因安裝時的最新版本略有不同）：

"dependencies": {"@modelcontextprotocol/sdk": "^1.13.1","zod": "^3.25.6"
}

這說明兩個庫已經成功安裝，接下來可以開始編寫服務器代碼了。

步驟 3：構建基礎的 MCP 服務器

這一步我們會從零開始，逐步寫出能運行的基礎服務器代碼。打開之前創建的main.ts文件，跟著以下步驟操作。

1. 導入需要的工具（代碼開頭）

首先，我們需要從剛才安裝的庫中 “導入” 要用的功能，就像做菜前把需要的食材拿出來一樣。在main.ts頂部添加以下代碼：

// 從MCP SDK中導入服務器核心類和通信工具
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
// 從Zod中導入數據驗證工具
import { z } from "zod";

McpServer：用于創建 MCP 服務器實例的類（服務器的 “主體”）；
StdioServerTransport：用于處理服務器與外部（比如 AI）通信的工具（通過終端的輸入輸出傳遞數據）；
z：Zod 庫的主入口，用于定義數據驗證規則。

2. 創建服務器實例

接下來，我們需要創建一個服務器實例，相當于 “啟動” 一個服務器程序。在導入代碼下方添加：

// 創建MCP服務器實例，指定名稱和版本
const server = new McpServer({name: "Weather Server",  // 服務器名稱（會告訴AI這是什么服務器）version: "1.0.0"         // 版本號（用于區分服務器的不同版本）
});

這行代碼會初始化一個服務器對象server，后續所有功能（比如定義工具、啟動通信）都要通過這個對象來操作。

3. 定義服務器的 “工具”—— 讓 AI 能調用的功能

MCP 服務器的核心是 “工具”（Tool）—— 這些工具是 AI 可以調用的功能。比如我們要實現 “查詢天氣”，就需要定義一個get-weather工具，告訴 AI：“你可以用這個工具查天氣，需要傳城市名作為參數”。

在服務器實例代碼下方添加：

// 給服務器添加一個名為"get-weather"的工具
server.tool('get-weather',  // 工具的唯一ID（AI調用時需要指定這個ID）'Tool to get the weather of a city',  // 工具描述（告訴AI這個工具能做什么）{  // 參數規則（用Zod定義，確保AI傳對參數）city: z.string().describe("The name of the city to get the weather for")},// 工具的實際功能（當AI調用時，會執行這個函數）async ({ city }) => {// 暫時返回一個靜態結果（后續會替換為調用真實天氣API）return {content: [{type: "text",  // 返回內容的類型是文本text: `The weather in ${city} is sunny`  // 具體文本內容}]};}
);

這段代碼的每個部分都很關鍵，我們拆開來解釋：

第一個參數'get-weather'：工具的唯一標識，AI 必須通過這個 ID 才能調用該工具（比如 AI 會說 “調用 get-weather 工具，參數是 city: 北京”）。
第二個參數'Tool to get the weather of a city'：給 AI 看的描述，讓 AI 知道這個工具的用途（如果描述不清，AI 可能不會正確使用）。
第三個參數{ city: z.string().describe(...) }：定義工具需要的參數。這里用z.string()指定 “city 必須是字符串”，describe則告訴 AI 這個參數的含義（“需要查詢天氣的城市名稱”）。如果 AI 傳的參數不是字符串（比如傳了數字），Zod 會自動報錯，避免工具出錯。
第四個參數（函數）：工具的核心邏輯。當 AI 調用get-weather工具時，這個函數會被執行，參數city就是 AI 傳過來的城市名。目前我們先返回一個靜態結果（比如 “北京的天氣是晴天”），后續會改成調用真實的天氣 API 獲取實時數據。

4. 配置服務器的通信方式

服務器創建好了，工具也定義了，最后需要讓服務器 “能聽能說”—— 也就是配置通信方式，讓它能接收 AI 的請求，并返回結果。

在工具定義代碼下方添加：

// 創建基于終端輸入輸出的通信工具
const transport = new StdioServerTransport();
// 讓服務器通過這個通信工具啟動
server.connect(transport);

StdioServerTransport：這是一種簡單的通信方式，通過終端的stdin（標準輸入）接收 AI 的請求，通過stdout（標準輸出）返回結果。對于本地開發和測試來說，這種方式足夠用了。
server.connect(transport)：讓服務器通過這個通信工具 “上線”，開始等待 AI 的調用。

完整的基礎服務器代碼

到這里，main.ts的完整代碼如下：

// 導入所需的工具
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from "zod";// 創建服務器實例
const server = new McpServer({name: "Weather Server",version: "1.0.0"
});// 定義get-weather工具
server.tool('get-weather','Tool to get the weather of a city',{city: z.string().describe("The name of the city to get the weather for")},async ({ city }) => {return {content: [{type: "text",text: `The weather in ${city} is sunny`}]};}
);// 配置通信并啟動服務器
const transport = new StdioServerTransport();
server.connect(transport);

測試基礎服務器（可選）

現在我們可以運行這個服務器，看看它是否能正常工作。在終端中執行：

npm start  # 這個命令會通過package.json中配置的ts-node運行main.ts

如果一切正常，終端會顯示服務器啟動的信息（可能是空白或簡單的日志），此時服務器處于 “等待狀態”，隨時可以接收 AI 的調用。

（注：目前這個服務器還只能返回靜態結果，下一部分我們會連接真實的天氣 API，讓它能返回實時數據。）

步驟 4：使用 MCP Inspector 進行測試

在添加真實天氣數據之前，讓我們使用 MCP Inspector（一個基于 Web 的 MCP 服務器調試工具）測試我們的服務器。

啟動檢查器

運行此命令以打開服務器的 MCP 檢查器：

npx -y @modelcontextprotocol/inspector npx -y tsx main.ts

運行該命令后，您將看到終端輸出：

本地主機 URL（例如http://127.0.0.1:6274）
唯一的會話令牌
預先填充了令牌的直接鏈接

💡提示：單擊已包含令牌的鏈接以避免手動輸入。

連接并測試

連接：單擊檢查器中的“連接”按鈕
導航：點擊頂部導航中的“工具”
選擇：選擇您的get-weather工具
測試：輸入城市名稱（例如“帕爾馬”），然后單擊“運行工具”

應該會看到響應："The weather in Palma de Mallorca is sunny"

故障排除：

連接錯誤？請確保使用的鏈接已預填充令牌

太棒了！構建的?MCP 服務器已經正常運行了。現在，讓我們讓它真正發揮作用。

步驟5：添加真實天氣數據

是時候讓我們的服務器真正發揮作用了！我們將與Open-Meteo集成，這是一個免費的天氣 API，無需 API 密鑰。

天氣 API 的工作原理

要獲取天氣數據，我們需要一個兩步過程：

轉換城市名稱→坐標（使用地理編碼 API）
使用坐標獲取天氣（使用天氣 API）

更新工具功能

用此增強版本替換您現有的工具功能：

server.tool('get-weather','Tool to get the weather of a city',{city: z.string().describe("The name of the city to get the weather for")},async({ city }) => {try {// Step 1: Get coordinates for the cityconst geoResponse = await fetch(`https://geocoding-api.open-meteo.com/v1/search?name=${city}&count=1&language=en&format=json`);const geoData = await geoResponse.json();// Handle city not foundif (!geoData.results || geoData.results.length === 0) {return {content: [{type: "text",text: `Sorry, I couldn't find a city named "${city}". Please check the spelling and try again.`}]};}// Step 2: Get weather data using coordinatesconst { latitude, longitude } = geoData.results[0];const weatherResponse = await fetch(`https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&current=temperature_2m,relative_humidity_2m,apparent_temperature,precipitation,weather_code&hourly=temperature_2m,precipitation&forecast_days=1`);const weatherData = await weatherResponse.json();// Return the complete weather data as JSONreturn {content: [{type: "text",text: JSON.stringify(weatherData, null, 2)}]};} catch (error) {return {content: [{type: "text",text: `Error fetching weather data: ${error.message}`}]};}}
);

測試真實數據

重新啟動MCP Inspector（Ctrl+C，然后重新運行命令）
在 Web 界面重新連接
使用“東京”或“紐約”等真實城市進行測試

現在應該能看到真實的天氣數據，而不是“晴天”了！🌤?

第六步：將天氣服務器與 VS Code 和 GitHub Copilot 集成

到這一步，我們已經搭建好了能返回實時天氣數據的 MCP 服務器。接下來，我們要讓它和 VS Code（代碼編輯器）、GitHub Copilot（AI 助手）“連起來”，這樣在寫代碼時，就能直接問 Copilot 天氣了。

準備工作

在開始前，請確保：

你的 MCP 服務器代碼（main.ts）已經保存，并且能正常運行（之前測試過返回天氣數據）；
VS Code 已安裝，且安裝了 “GitHub Copilot” 插件（如果沒裝，在 VS Code 的 “擴展” 面板搜索 “GitHub Copilot” 并安裝，需要登錄 GitHub 賬號）。

第一步：在 VS Code 中注冊你的天氣服務器

注冊的目的是告訴 VS Code：“我有一個本地的 MCP 服務器，地址是 xxx，你可以通過它和 Copilot 通信”。具體步驟如下：

打開 VS Code，確保已經打開我們的項目文件夾（mcp-weather-server）。
打開 VS Code 的 “命令面板”：
- Windows/Linux 用戶：按?Ctrl + Shift + P
- Mac 用戶：按?Cmd + Shift + P
在命令面板中輸入?MCP: Add Server，然后按回車（這是 VS Code 中 MCP 相關的命令，用于添加新服務器）。
選擇服務器類型：在彈出的選項中，選擇 “使用 stdio 的本地服務器”（因為我們的服務器是通過終端輸入輸出通信的，和本地程序一樣）。
輸入啟動服務器的命令：
在 “輸入命令” 的提示框中，輸入?npx -y tsx main.ts。
- 解釋：npx?是用來運行本地安裝的工具的命令；tsx?是一個能直接運行 TypeScript 代碼的工具（類似之前的ts-node）；main.ts?是我們的服務器入口文件。
  這個命令的作用是：讓 VS Code 知道 “如何啟動你的服務器”。
給服務器起個名字：在 “姓名” 提示框中，輸入?my-weather-server（可以自定義，方便后續識別）。
選擇安裝類型：在彈出的選項中，選擇 “本地設置”（表示這個服務器配置只在當前項目中生效，不會影響其他項目）。

第二步：確認服務器配置文件

完成注冊后，VS Code 會在你的項目文件夾中自動創建一個?.vscode?文件夾，里面有一個?mcp.json?文件。這個文件記錄了服務器的配置信息，內容類似：

{"inputs": [],"servers": {"my-weather-server": {"type": "stdio","command": "npx","args": ["-y","tsx","/Users/你的用戶名/項目路徑/main.ts"  // 這里是你main.ts的實際路徑]}}
}

這個文件的作用是：告訴 VS Code “啟動服務器需要執行什么命令”“服務器的類型是什么”。不用手動修改，保持默認即可。

第三步：啟動服務器并測試與 Copilot 的連接

現在我們要啟動服務器，然后讓 Copilot 調用它來查詢天氣。

打開 VS Code 的 MCP 面板：
在 VS Code 左側的活動欄中，找到并點擊 “MCP” 圖標（通常是一個類似 “工具” 的圖標，如果沒找到，可以在 “擴展” 中搜索 “MCP” 插件并確保已啟用）。
啟動服務器：
在 MCP 面板中，找到你剛才注冊的?my-weather-server，它的狀態應該是 “未運行”。點擊服務器名稱旁邊的 “啟動” 按鈕（通常是一個三角形的 “播放” 圖標）。
- 啟動后，狀態會變成 “正在運行”，表示服務器已經啟動成功，隨時可以接收 Copilot 的請求。
切換 Copilot 到 “代理模式”：
在 VS Code 左側的活動欄中，點擊 “GitHub Copilot” 圖標，打開 Copilot 側邊欄。在側邊欄中，找到并點擊 “代理模式”（Proxy Mode）—— 這個模式會讓 Copilot 知道 “可以調用外部工具（比如我們的天氣服務器）”。
向 Copilot 詢問天氣：
在 Copilot 的輸入框中，輸入問題，比如 “東京的天氣怎么樣？”，然后按回車。
允許 Copilot 調用工具：
第一次調用時，Copilot 會彈出一個提示：“是否允許使用 my-weather-server 中的 get-weather 工具？”，點擊 “繼續” 或 “允許”。

第四步：查看結果

稍等片刻，Copilot 會返回類似這樣的結果：

東京今日天氣
溫度：28°C（體感 32°C）
濕度：75%
天氣狀況：多云，傍晚預計有小雨

這說明：Copilot 成功調用了我們的天氣服務器，獲取到實時數據后，還自動整理成了易讀的格式（而不是原始的 JSON 數據）。

為什么這個功能很有用？

到這里，你可能會好奇：這個集成到底解決了什么問題？

AI 能直接用你的工具：以前 Copilot 因為沒有實時數據接口，無法回答天氣問題；現在通過你的 MCP 服務器，它能主動調用工具獲取數據，相當于給 AI 裝了 “實時數據接口”。
一次開發，多處可用：只要服務器符合 MCP 協議，不僅能和 GitHub Copilot 配合，還能和其他支持 MCP 的 AI 工具（比如 Claude、ChatGPT 的插件模式）兼容，不用重復開發。
數據實時更新：服務器每次調用都會請求天氣 API 的最新數據，不會有緩存過期的問題，確保信息是最新的。
易于擴展：后續你可以給服務器添加更多工具，比如 “查詢未來 3 天的天氣”“獲取空氣質量指數”，只需要在main.ts中新增工具定義，Copilot 會自動識別并使用這些新功能。

完整代碼參考

這是最終main.ts文件：

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { z } from "zod";const server = new McpServer({name: "Weather Server",version: "1.0.0"
});server.tool('get-weather','Tool to get the weather of a city',{city: z.string().describe("The name of the city to get the weather for")},async({ city }) => {try {const response = await fetch(`https://geocoding-api.open-meteo.com/v1/search?name=${city}&count=10&language=en&format=json`);const data = await response.json();if (data.results.length === 0) {return {content: [{type: "text",text: `No results found for city: ${city}`}]};}const { latitude, longitude } = data.results[0];const weatherResponse = await fetch(`https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}&hourly=temperature_2m,precipitation,apparent_temperature,relative_humidity_2m&forecast_days=1`);const weatherData = await weatherResponse.json();return {content: [{type: "text",text: JSON.stringify(weatherData, null, 2)}]};} catch (error) {return {content: [{type: "text",text: `Error fetching weather data: ${error.message}`}]};}}
);const transport = new StdioServerTransport();
server.connect(transport);

下一步：增強服務器

準備好將構建好的天氣服務器提升到一個新的水平了嗎？以下是一些建議：

🚀 額外的天氣工具

延伸預測

server.tool('get-forecast', 'Get 7-day weather forecast', ...)

天氣警報

server.tool('get-alerts', 'Get severe weather warnings', ...)

空氣質量

server.tool('get-air-quality', 'Get air pollution data', ...)

共享搭建的屬于自己的服務器

發布到 NPM：讓其他人可以使用

結論

🎉恭喜！已成功搭建屬于自己的第一個 MCP 天氣服務器！

您所取得的成就：

? 從零開始創建功能齊全的 MCP 服務器
? 集成來自外部 API 的實時天氣數據
? 將其連接到 VS Code 和 GitHub Copilot
? 學習了模型上下文協議的基礎知識

關鍵要點：

簡單：?MCP 服務器的構建比看起來要容易得多
力量：真實數據使人工智能交互更有價值
靈活性：同一服務器可跨多個 AI 平臺工作
面向未來：您正在構建下一代人工智能的基礎設施

下一步是什么？可能性無窮無盡！天氣只是個開始，現在你可以將 AI 連接到數據庫、API、文件系統以及你能想到的任何服務。

祝各位讀者搭建愉快！🚀