🧠 Windows 下的 Codex CLI MCP 配置完全指南

在 Windows 環境下配置 OpenAI Codex CLI 的 MCP（Model Context Protocol，模型上下文協議）伺服器 可能會碰到不少錯誤與困惑。本篇文章將帶你從 官方概念、正確設定方法、常見錯誤排查 到 實用範例 都一併整理，目標是讓你在 Windows 上可以順利啟動並使用各種 MCP。（OpenAI Developers）

---

📌 MCP 是什麼？（根據 OpenAI 官方定義）

MCP（Model Context Protocol） 是一種 開放標準協議，用來連接大型語言模型（LLM）與外部工具、資料服務與其他資源。透過 MCP 協議，你可以讓模型在對話或任務過程中透過標準化方式呼叫外部工具、返回結果以及附加元資料。（OpenAI Developers）

你可以把 MCP 想像成 AI 應用的「USB-C 連接埠」：它提供一種標準化管道，讓 AI 模型無論在哪裡執行，都可以連接到各種工具、資料庫和服務。（OpenAI GitHub）

根據 OpenAI 官方，Codex CLI 和 IDE 擴充套件均 支援 MCP 客戶端，並可透過 .codex/config.toml 指定 MCP 伺服器設定。（OpenAI Developers）

---

📁 MCP 的配置位置與管理方式（官方推薦）

🔹 MCP 設定檔位置

Codex 儲存 MCP 配置的位置如下：

C:\Users\<你的使用者名稱>\.codex\config.toml

這個檔案也會同時包含其他 Codex 設定（如 CLI 設定）。你可以直接編輯此檔案，或使用 CLI 管理 MCP。（OpenAI Developers）

🔹 CLI 管理 MCP 伺服器

使用 Codex CLI，也可以透過指令新增或管理 MCP 伺服器：

codex mcp add <name> -- <command...>
codex mcp list
codex mcp get <name>

例如列出所有 MCP 設定：

codex mcp list --json

更多 codex mcp 命令與選項請參考官方 CLI 參考文件。（OpenAI Developers）

---

⚙️ 為什麼 Windows 配置會容易失敗？（重點整理）

實際使用中，Windows 下 MCP 配置可能會遇到以下錯誤：

• ✔️ 程式找不到 program not found
• ✔️ 伺服器啟動超時 request timed out
• ✔️ TOML 格式錯誤 newlines are unsupported in inline tables

這通常是環境變數、TOML 格式、以及 Node.js 運行環境設定不正確所造成的。（Sanshao Technology Blog）

---

🧩 MCP 正確配置方法（實用示例）

以下示例都是以 Windows .codex/config.toml 為主，並避免內聯表格換行、必要環境變數逐行寫法等技巧，能有效避免格式與啟動錯誤。（Sanshao Technology Blog）

🔹 1. Playwright MCP（網頁測試 / 自動化）

[mcp_servers.playwright]
type = "stdio"
command = "cmd"
args = ["/c", "npx", "-y", "@playwright/mcp@latest"]
startup_timeout_ms = 180000
env = {
  APPDATA = "C:\\Users\\<你的使用者名稱>\\AppData\\Roaming",
  LOCALAPPDATA = "C:\\Users\\<你的使用者名稱>\\AppData\\Local",
  HOME = "C:\\Users\\<你的使用者名稱>",
  SystemRoot = "C:\\Windows",
  NODE_OPTIONS = "--dns-result-order=ipv4first"
}

這個 MCP 用於啟動 Playwright 相關操作，例如網頁互動與自動化。（Sanshao Technology Blog）

🔹 2. Memory LibSQL MCP（連接資料庫）

[mcp_servers.mcp-memory-libsql]
type = "stdio"
command = "cmd"
args = ["/c", "npx", "-y", "mcp-memory-libsql"]
startup_timeout_ms = 180000

[mcp_servers.mcp-memory-libsql.env]
LIBSQL_URL = "libsql://<你的資料庫名稱>.turso.io"
LIBSQL_AUTH_TOKEN = "<你的認證令牌>"
APPDATA = "C:\\Users\\<你的使用者名稱>\\AppData\\Roaming"
LOCALAPPDATA = "C:\\Users\\<你的使用者名稱>\\AppData\\Local"
HOME = "C:\\Users\\<你的使用者名稱>"
SystemRoot = "C:\\Windows"
NODE_OPTIONS = "--dns-result-order=ipv4first"

此 MCP 可讓 Codex 透過 LibSQL 操作遠端資料庫。（Sanshao Technology Blog）

🔹 3. Context7 MCP（記憶 / 上下文管理）

[mcp_servers.context7]
type = "stdio"
command = "cmd"
args = ["/c", "npx", "-y", "@upstash/context7-mcp", "--api-key", "<你的 Context7 API Key>"]
startup_timeout_ms = 120000
env = {
  APPDATA = "C:\\Users\\<你的使用者名稱>\\AppData\\Roaming",
  LOCALAPPDATA = "C:\\Users\\<你的使用者名稱>\\AppData\\Local",
  HOME = "C:\\Users\\<你的使用者名稱>",
  SystemRoot = "C:\\Windows",
  NODE_OPTIONS = "--dns-result-order=ipv4first"
}

此 MCP 適用於需將上下文狀態保留 / 管理的情況。（Sanshao Technology Blog）

🔹 4. Supabase MCP（Supabase 資料庫 & API）

[mcp_servers.supabase]
type = "stdio"
command = "cmd"
args = ["/c", "npx", "-y", "@supabase/mcp-server-supabase@latest", "--read-only", "--project-ref=<你的 project ref>"]
startup_timeout_ms = 120000
env = {
  APPDATA = "C:\\Users\\<你的使用者名稱>\\AppData\\Roaming",
  LOCALAPPDATA = "C:\\Users\\<你的使用者名稱>\\AppData\\Local",
  HOME = "C:\\Users\\<你的使用者名稱>",
  SystemRoot = "C:\\Windows",
  NODE_OPTIONS = "--dns-result-order=ipv4first",
  SUPABASE_ACCESS_TOKEN = "<你的 Supabase Token>"
}

此 MCP 可讓模型與 Supabase 資料庫 / 服務互動。（Sanshao Technology Blog）

---

💡 常見錯誤與排查建議

• ✔️ TOML 格式錯誤
  請避免在內聯 {} 中換行，改用逐行標準表格格式。
• ✔️ 啟動超時
  如遇 request timed out，可提高 startup_timeout_ms，並確認所有環境變數完整。
• ✔️ 程式找不到
  因為 Windows 命令行處理特殊字符，請務必使用 cmd /c <command> 格式。

---

🔁 替代方案（官方與實務推薦）

若 Windows 環境實在太難配置：

• ✅ WSL（Windows Subsystem for Linux）
  在 WSL Linux 環境中安裝與執行 Codex CLI，可避免 Windows 原生環境的許多限制。

wsl --install
npm install -g @openai/codex

---

🏁 結語：Windows MCP 設定成功的關鍵

• 理解 MCP 協議是模型與工具連接的標準化管道（官方定義）
• 完整設定環境變數與正確的 TOML 格式（減少錯誤）
• 在必要時使用 WSL 或 Docker 作為替代方案（提高穩定性）

通過本文整理的示例與技巧，你應該可以更加順利地在 Windows 下配置 Codex MCP。若你有其他 MCP 用例或想加入更多工具整合例子，也歡迎留言討論！🚀