Claude Code 添加 MCP 伺服器完整指南：從入門到精通

KoiCode

更新於 2025/08/18發佈於 2025/08/18閱讀時間約 16 分鐘

本文包含最新的 MCP 設定方法、常見錯誤解決方案，以及 10 個經過測試的實用 MCP 伺服器推薦。解決 90% 以上的設定問題！

你是否在使用 Claude Code 時想要擴充更多功能？是否遇過「MCP 伺服器添加失敗」的錯誤？更重要的是，你是否在為高昂的費用和不穩定的帳號而煩惱？

本文將一步步教你如何正確添加和設定 MCP 伺服器，讓你的 Claude Code 功能提升 10 倍！讀到最後，我們還會為你揭曉一個徹底解決成本和封號問題的終極方案。

~~快速提示：~~ ~~如果你只想快速添加一個 MCP 伺服器，直接跳到「30 秒快速上手」部分。如果你想深入了解並避免所有可能的錯誤，請完整閱讀本文。~~

什麼是 MCP？

MCP 是 Anthropic 推出的開源通訊標準，它就像是 AI 助手的「手腳」，讓 Claude Code 可以：

直接存取和操作本機檔案系統
連接各種 API 和網路服務
查詢和操作資料庫
整合各種開發工具
自動化日常任務

30 秒快速上手

如果你趕時間，這是最快的添加方法（檔案系統存取，最常用）：

# 添加檔案系統存取（最常用）
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Desktop

# 驗證是否成功
claude mcp list

執行添加檔案系統存取的命令。
執行驗證命令確認是否成功。
就這麼簡單！但如果遇到錯誤，請繼續閱讀詳細指南。

詳細添加步驟（3 種方法）

方法 1：命令列添加（推薦新手）

# 基本語法
claude mcp add &lt;名称&gt; &lt;命令&gt; [参数...]

# 實際例子：添加本機檔案系統存取
claude mcp add my-filesystem -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

# 帶環境變數的例子
claude mcp add api-server -e API_KEY=your-key-here -- /path/to/server

Claude Code 提供了簡單的命令列工具來添加 MCP 伺服器。基本語法是指定名稱、命令和參數。實際例子包括添加本機檔案系統存取或帶有環境變數的 API 伺服器。

方法 2：直接編輯組態檔（推薦進階使用者）

很多開發者覺得命令列精靈太繁瑣。直接編輯組態檔更高效：

1.找到組態檔位置：

macOS/Linux: ~/.claude.json

Windows: %USERPROFILE%\.claude.json

2.編輯組態檔：

{"mcpServers":{"filesystem":{"type":"stdio","command":"npx","args":["-y","@modelcontextprotocol/server-filesystem","/Users/username/Documents"],"env":{}},"github":{"type":"stdio",
      "command":"npx","args":["-y","@modelcontextprotocol/server-github"],"env":{"GITHUB_TOKEN":"your-github-token"}}}}

3.重新啟動 Claude Code 生效

方法 3：專案層級設定（推薦團隊協作）

如果想讓團隊成員都能使用相同的 MCP 設定：

# 添加專案層級 MCP 伺服器
claude mcp add shared-tools -s project -- npx -y @your-team/mcp-tools

會在專案根目錄建立 .mcp.json 檔案：

{"mcpServers": {"shared-tools": {"command": "npx","args": ["-y", "@your-team/mcp-tools"],"env": {}}}}

MCP 伺服器作用域詳解

理解作用域對於避免「找不到伺服器」的錯誤至關重要：

Local 作用域（預設）： 只在目前目錄可用，設定儲存在使用者的 Claude 組態檔中。適合個人專案特定工具。
User 作用域（全域）： 在所有專案中都可用，使用特定旗標添加。適合常用工具如檔案系統、資料庫用戶端。
Project 作用域（團隊共享）： 透過專案目錄下的設定檔共享，使用特定旗標添加。適合團隊共享的專案特定工具。

10 個最實用的 MCP 伺服器推薦

基於社群回饋和實際使用經驗，這是最值得安裝的 MCP 伺服器清單：

1.檔案系統存取：

claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects ~/Desktop

用途：讓Claude直接讀寫檔案，修改程式碼

2.GitHub 整合：

claude mcp add github -s user -e GITHUB_TOKEN=your-token -- npx -y @modelcontextprotocol/server-github

用途：管理議題、拉取請求（PR）、程式碼審查

3.網頁瀏覽器控制：

claude mcp add puppeteer -s user -- npx -y @modelcontextprotocol/server-puppeteer

用途：自動化網頁操作、爬蟲、測試

4.資料庫連接（PostgreSQL）：

claude mcp add postgres -s user -e DATABASE_URL=your-db-url -- npx -y @modelcontextprotocol/server-postgres

用途：直接查詢和操作資料庫

5.Fetch 工具（API 呼叫）：

claude mcp add fetch -s user -- npx -y @kazuph/mcp-fetch

用途：調用各種 REST API

6.搜尋引擎：

claude mcp add search -s user -e BRAVE_API_KEY=your-key -- npx -y @modelcontextprotocol/server-brave-search

用途：搜尋最新資訊

7.Slack 整合：

claude mcp add slack -s user -e SLACK_TOKEN=your-token -- npx -y @modelcontextprotocol/server-slack

用途：傳送訊息、管理頻道

8.時間管理：

claude mcp add time -s user -- npx -y @modelcontextprotocol/server-time

用途：時區轉換、日期計算

9.記憶體儲存：

claude mcp add memory -s user -- npx -y @modelcontextprotocol/server-memory

用途：跨對話儲存資訊

10.Sequential Thinking（思維鏈）：

claude mcp add thinking -s user -- npx -y @modelcontextprotocol/server-sequential-thinking

用途：協助 Claude 對複雜問題分步驟思考。

常見錯誤及解決方案

錯誤 1：工具名稱驗證失敗

API Error 400: "tools.11.custom.name: String should match pattern '^[a-zA-Z0-9_-]{1,64}

解决方案：
確保伺服器名稱只包含字母、數字、底線和連字號
名稱長度不超過64個字元
不要使用特殊字元或空格

錯誤2：找不到MCP伺服器

MCP server 'my-server' not found

解決方案：
檢查作用域設定是否正確
執行 claude mcp list 指令確認伺服器已新增
確保位於正確的目錄下 (適用於 local 作用域)
重啟 Claude Code

錯誤 3：通訊協定版本錯誤

"protocolVersion": "Required"

解決方案：
這是 Claude Code 的已知程式錯誤，臨時解決方案：
使用包裝腳本
確保 MCP 伺服器回傳正確的通訊協定版本
更新到最新版本的 Claude Code

錯誤 4：Windows 路徑問題

Error: Cannot find module 'C:UsersusernameDocuments'

解決方案：
Windows 路徑需使用正斜線或雙反斜線：
```bash
錯誤
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Documents
正確
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:/Users/username/Documents
或
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem C:\\Users\\username\\Documents

錯誤 5：權限問題

Permission denied

解決方案：
macOS/Linux： 使用 sudo（不建議）或修改檔案權限
Windows： 以系統管理員身分執行
最佳做法： 將 MCP 伺服器安裝在使用者目錄

除錯技巧

當遇到問題時，這些除錯方法可協助你迅速找出問題根源：

1.啟用除錯模式：

claude --mcp-debug

2.查看 MCP 狀態：

在 Claude Code 對話視窗中輸入：

/mcp

3.查看記錄檔：

macOS/Linux:

tail -f ~/Library/Logs/Claude/mcp*.log

Windows:

type "%APPDATA%\Claude\logs\mcp*.log"

4.手動測試伺服器：

直接執行伺服器命令，觀察輸出是否正常：

npx -y @modelcontextprotocol/server-filesystem ~/Documents

中文用戶特別注意事項

1.中文路徑問題：

強烈建議避免在 MCP 伺服器設定路徑中使用中文字元，改用英文路徑名稱：

避免
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem ~/文件

推薦
claude mcp add fs -- npx -y @modelcontextprotocol/server-filesystem ~/Documents

2.代理伺服器設定：

若使用代理，需先設定 npm 的 proxy 和 https-proxy 環境變數：

設定 npm 代理伺服器

npm config set proxy http://your-proxy:port
npm config set https-proxy http://your-proxy:port

再添加 MCP 伺服器：

claude mcp add ...

最佳實務建議

依需求新增： 不要一次全數新增太多 MCP 伺服器，會影響效能
定期清理： 使用 claude mcp remove <name> 移除不用的伺服器
安全第一： 只新增可信賴的 MCP 伺服器，特別是需開放網路存取的
備份設定檔： 定期備份 ~/.claude.json 檔案
團隊協作： 使用 project 作用域共用常用設定

進階技巧

建立自訂 MCP 伺服器：

若現有伺服器不符需求，可使用 MCP SDK 開發自訂伺服器：

// my-mcp-server.jsimport { Server } from '@modelcontextprotocol/sdk';

const server = newServer({
name: 'my-custom-server',
version: '1.0.0',
});

server.setRequestHandler('tools/list', async () =&gt; {
return {
    tools: [{
      name: 'my_custom_tool',
      description: '自訂工具',
      inputSchema: {
        type: 'object',
        properties: {
          input: { type: 'string' }
        }
      }
    }]
  };
});

server.start();

批次設定腳本：

建立一個腳本一次完成所有常用 MCP 伺服器的設定：

#!/bin/bash# setup-mcp.shecho "正在設定常用 MCP 伺服器..."# 檔案系統
claude mcp add filesystem -s user -- npx -y @modelcontextprotocol/server-filesystem ~/Documents ~/Projects

# GitHubread -p "請輸入GitHub Token: " github_token
claude mcp add github -s user -e GITHUB_TOKEN=$github_token -- npx -y @modelcontextprotocol/server-github

# 其他伺服器...echo "設定完成！"
claude mcp list