2025-05-02-MacBook Air（macOS）上架設一個可跑的 MCP server

發表於 2025-09-16 更新於 2025-09-17 分類於 OneDayOneNote 閱讀次數：

一步步在舊 MacBook Air（macOS）上架設一個可跑的 MCP server（採 Node.js 範例），並把每一步該執行的 Terminal 指令、檢查點和常見問題一起寫清楚。
我選 Node.js 路線（因為你熟 Vue/JS，Node 生態整合比較順），如果之後你想要 Python 範例我也可以再給出來。

重要事實先說：MCP 有官方 Node / Python SDK，Node 需要 **Node 18+**；Python 路線需 **Python 3.10+**。官方 MCP quickstart 與 Node SDK 文件是本教學的依據。(modelcontextprotocol.io)

總體步驟（概覽）

確認 macOS 版本與 CPU 架構（很重要）
安裝開發工具（Xcode Command Line Tools）
安裝 Homebrew（macOS 的套件管理）並用它安裝 nvm（Node 版本管理）
用 nvm 安裝 Node 18 並驗證
建立簡單的 MCP Node 專案（安裝 @modelcontextprotocol/sdk）並貼上範例程式碼
執行 MCP server（stdio transport）並把它接到支援 MCP 的客戶端（例如 Claude Desktop）
簡單除錯與注意事項

下面把每一步細化成可直接複製執行的命令與說明。

1) 檢查 macOS 版本與 CPU 架構（先做）

在 Terminal 執行：

1 2	sw_vers -productVersion uname -m

sw_vers -productVersion 會回傳像 10.15.7、12.6、13.6 等（macOS Catalina / Monterey / Ventura 等）。也可從「 → About This Mac」看。(Mac Mini Vault)
uname -m 會回傳 x86_64（Intel）或 arm64（Apple Silicon / M1/M2）。

建議：若能升到 macOS 10.15+ (Catalina) 或更新會最順（Node 18 預建二進位針對 10.15+；Apple Silicon 建議 macOS 11+）。若太舊、安裝新版有困難，請回報版本號我再給替代方案（例如在 Windows/雲端跑）。(GitHub)

2) 安裝 Xcode Command Line Tools（必要）

如果尚未安裝：

1	xcode-select --install

安裝完會提供 git、編譯工具等，之後 Homebrew 與某些套件需要它。

3) 安裝 Homebrew（如果還沒裝）

Homebrew 用來安裝 nvm / python 等工具，官方安裝指令：

1	/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

（執行後依指示把 Homebrew 的路徑加到 shell 設定檔）(維基百科)

4) 安裝 nvm（Node 版本管理）並安裝 Node 18（推薦）

用 nvm 可以避免系統 Node 衝突：

brew install nvm
mkdir -p ~/.nvm
# 把下面兩行加入你的 shell 設定檔 (~/.zshrc 或 ~/.bash_profile)
echo 'export NVM_DIR="$HOME/.nvm"' >> ~/.zshrc
echo 'source $(brew --prefix nvm)/nvm.sh' >> ~/.zshrc
# 立刻套用
source ~/.zshrc

# 安裝 Node 18 LTS
nvm install 18
nvm use 18
node -v   # 應顯示 v18.x.x
npm -v

若你不想用 nvm，也可以 brew install node@18，但 nvm 更方便切換版本。
Node 18 是官方建議用於 MCP SDK 的最低版本。(npm)

5) 建立 MCP Node 範例專案（從零開始）

在家目錄建立資料夾並安裝 SDK：

mkdir ~/mcp-server
cd ~/mcp-server
npm init -y
npm i @modelcontextprotocol/sdk zod

建立檔案 server.mjs（使用 ESM，Node 18 支援 top-level await） — 把下面程式碼貼進去（這是一個極簡的 demo，提供一個 add 工具）：

// server.mjs
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: "demo-mcp", version: "0.1.0" });

// 註冊一個簡單工具：add
server.registerTool(
  "add",
  {
    title: "Addition",
    description: "Add two numbers",
    inputSchema: { a: z.number(), b: z.number() }
  },
  async ({ a, b }) => {
    return { content: [{ type: "text", text: String(a + b) }] };
  }
);

// 使用 stdio transport（常用於桌面客戶端如 Claude Desktop）
const transport = new StdioServerTransport();
await server.connect(transport);

// 注意：不要用 console.log() 打到 stdout，會干擾 MCP 協議。
// 若要記錄請用 console.error() 或寫檔。
console.error("MCP server started: demo-mcp");

執行：

1	node server.mjs

如果看到沒有錯誤、且沒有把 JSON 輸出到屏幕，那麼 server 應該已啟動並等待 MCP 客戶端透過 stdio 與它通訊。Node SDK 的用法與範例可參考官方文件（上面程式取自官方 quickstart 範例）。(npm)

6) 在客戶端（例如 Claude Desktop）註冊你的 MCP server

以 Claude for Desktop 為例（官方 quickstart 示範）：

打開或建立設定檔：

1	code ~/Library/Application\ Support/Claude/claude_desktop_config.json

在 mcpServers 裡加一段（路徑請改成你的絕對路徑）：

{
  "mcpServers": {
    "demo-mcp": {
      "command": "node",
      "args": [ "/Users/yourname/mcp-server/server.mjs" ]
    }
  }
}

儲存後重啟 Claude Desktop，應該會在工具/設定中看到 demo-mcp 的工具（若沒有，檢查路徑與 Node 版本）。官方 quickstart 有相同範例可參考。(modelcontextprotocol.io)

重點提醒：當使用 stdio transport 時，請 絕對不要 在程式中用 console.log() 或 print() 輸出到 stdout（會破壞 MCP JSON-RPC），可用 console.error() 或 log 檔案。(modelcontextprotocol.io)

7) 簡單除錯清單（常見問題）

沒啟動 / 客戶端抓不到 server：檢查 claude_desktop_config.json 的 command 與 args 路徑是否為絕對路徑，並重啟客戶端。(modelcontextprotocol.io)
程式錯誤、stacktrace 顯示在 stdout：確定不要把錯誤輸出到 stdout；Node 的 console.error() 會到 stderr。
Node 版本太低：node -v 顯示要 >= v18.x。若不是，使用 nvm install 18。(npm)
macOS 太舊安裝 Node 有問題：有些極舊 macOS 需編譯 Node（比較麻煩），若遇到可回報你的 sw_vers 我幫你看要不要升級或用其他方案（如在 Windows/雲端跑）。(GitHub)

8) 如果你想用 Python 路線（快速說明）

官方 quickstart 用 Python 的 FastMCP 非常直接，需求是 **Python 3.10+**。快速步驟（官方推薦使用 uv 工具來管理）：

# 安裝 uv 執行器（官方 quickstart 建議）
curl -LsSf https://astral.sh/uv/install.sh | sh
# 重新開 terminal
uv init weather
cd weather
uv venv
source .venv/bin/activate
uv add "mcp[cli]" httpx
# 建立 weather.py 並參考 quickstart 範例
uv run weather.py

詳細 Python 範例請參考官方 quickstart。若你想要我把 Python 版本的完整步驟與 weather.py 範例貼給你，我可以接著做。(modelcontextprotocol.io)

小結與我接下來可以幫你的事

我已經為你準備好：完整 Node.js 路線的 step-by-step，包含檢查 macOS、安裝 Homebrew、nvm、Node、建立 server.mjs、如何在 Claude Desktop 註冊。主要參考來自官方 MCP quickstart 與 Node SDK 文件。(modelcontextprotocol.io)
下一步（你可以選一個）：
1. 我直接把 server.mjs 寫成你可以直接複製貼上、完全可跑的檔案（包含更完整的 error-handling 與 README）——我已包含簡短範例，要我昇級成更完整的 demo 嗎？
2. 或我把 Python (weather.py) 的完整步驟也貼上（如果你想走 Python 路線）。
3. 或你現在就照上面步驟做，有任何卡住的錯誤訊息（把完整 Terminal 訊息貼來），我幫你排錯。

你想要我現在把那個 server.mjs 的完整 ready-to-run 檔再貼一次（含 package.json 建議），還是你要先執行到哪個步驟我再支援？