裝第一個 MCP Server:十五分鐘接上

第 1 課講完 MCP 的概念,你知道它能讓 AI 連上外部工具——但那些「GitHub Server」、「Notion Server」現在對你來說還是貼在盒子上的標籤,一個都沒插進去。這堂課的目標就一個:讓你親手裝好第一個 MCP Server,看著 Claude 真的跑去讀你電腦裡的資料夾,從「我聽懂了」升級到「我自己搞定了」。

我們從官方 filesystem server 下手。它只做一件事:讓 AI 讀寫你指定的本機資料夾。選這個當第一課是有原因的——它不需要申請帳號、不需要 API 金鑰、不用架伺服器,本機裝好就動。更重要的是,裝這一個的過程會把整套 MCP 安裝流程走一遍,之後裝 GitHub、Notion、Stripe 任何 server,步驟都是同一套,差別只有 JSON 裡那幾個值不同。

裝好之後能做什麼?舉幾個具體的場景:你可以叫 Claude 掃你的 Downloads 資料夾、把三個月前下載的 PDF 整理分類;可以把一個專案資料夾開放給 AI,讓它跨越多份文件幫你寫整合報告;可以讓 Claude 直接改你本機的設定檔,不用複製貼上再貼回去。這些以前都得靠自己手動搬資料,現在 AI 自己去拿。

這堂學什麼

• Claude Desktop 和 Claude Code 各自的 MCP 設定檔在哪、格式長什麼樣
• 安裝官方 filesystem MCP Server 的完整步驟(含確認 Node.js 環境)
• 三種驗證 MCP 已連上的方法
• JSON 設定檔四大常見錯誤與對應解法
• 實戰:給 Claude 一個資料夾路徑,讓它列目錄、讀檔、建檔

觀念一:MCP 設定檔的角色

MCP 設定檔就是你告訴 Claude「你有哪些 server 可以用、要怎麼啟動它們」的名單。每次 Claude 啟動時,它會讀這份名單,把列出來的 server 一個個在背景跑起來,準備好之後才讓你開始對話。

檔案格式是 JSON,只有一個頂層鍵 mcpServers,底下每個 server 有幾個欄位:

{
  "mcpServers": {
    "server名稱（你自己取，隨意）": {
      "command": "啟動 server 用的執行檔",
      "args": ["傳給這個執行檔的參數", "每個參數獨立一個字串"]
    }
  }
}

command 是要執行的程式(最常見是 npx 或 node),args 是傳給這個程式的參數陣列。Claude 在背景把 command 加上 args 串起來執行——以 filesystem server 為例,它實際執行的就相當於:

npx -y @modelcontextprotocol/server-filesystem /你指定的資料夾路徑

-y 的意思是「自動同意安裝」,讓 npx 不用問你確認就把套件下載並執行。

這個 server 啟動之後,Claude 和它之間用標準輸入/輸出(stdin/stdout)通訊——這就是 MCP 協議的核心:一個穩定、語言無關的溝通管道。你寫 Python 或 Go 的 server 也是一樣接法,第 5 課自己做 server 時會再用到這個觀念。現在只要知道:設定檔告訴 Claude「這個 server 怎麼啟動」,剩下的握手和協議協商 Claude 自己處理。

觀念二:Claude Desktop vs Claude Code,設定檔不同地方

這兩個工具的 MCP 設定方式不一樣,別搞混。

這堂課以 Claude Desktop 為主要示範對象,Claude Code 的作法在最後一個步驟另行說明。

補充一個常見疑問:你同時裝了兩個工具,設定要做兩次嗎?對。Claude Desktop 和 Claude Code 的設定檔彼此獨立,裝在一個不代表另一個也有。好處是你可以依用途分開管理——Claude Desktop 可能開放你的個人資料夾,Claude Code 只開放目前這個工程專案的資料夾,不會互相干擾。

手把手實戰

node --version

brew install node

npx --version

open ~/Library/Application\ Support/Claude/

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/你的使用者名稱/Documents"
      ]
    }
  }
}

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "C:\\Users\\你的使用者名稱\\Documents"
      ]
    }
  }
}

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Documents",
        "/Users/yourname/Desktop"
      ]
    }
  }
}

filesystem
  read_file             — 讀取單一檔案內容
  read_multiple_files   — 一次讀多個檔案
  write_file            — 寫入/覆蓋檔案
  edit_file             — 局部編輯檔案(patch 模式)
  create_directory      — 建立資料夾
  list_directory        — 列出資料夾內容
  directory_tree        — 遞迴列出整個目錄樹
  move_file             — 移動或重新命名
  search_files          — 搜尋符合條件的檔案
  get_file_info         — 取得檔案 metadata

請幫我列出 /Users/yourname/Documents 的目錄結構,只顯示第一層,條列格式。

在 /Users/yourname/Documents 底下建立一個叫 mcp-test 的資料夾,
裡面建一個 hello.txt,內容寫:
「MCP 連線成功。裝置:我的電腦。日期:2026-07-04」

幫我搜尋 /Users/yourname/Documents 裡面所有副檔名是 .pdf 的檔案,
把結果整理成一份清單,包含每個檔案的名稱和大小。

claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /Users/yourname/Documents

claude mcp list

filesystem: npx -y @modelcontextprotocol/server-filesystem /Users/yourname/Documents

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Documents"
      ]
    }
  }
}

常見坑

坑 1:JSON 語法錯誤,錘子 icon 沒出現

JSON 格式非常嚴格,少一個逗號、多一個引號都會讓整份設定失效——而 Claude Desktop 不會跳錯誤視窗提醒你,就只是默默忽略整份設定。最常見的幾種寫法:

// 錯誤示範:最後一個屬性後面多了逗號
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/Documents"],
    }
  }
}

// 錯誤示範:args 的元素忘記加引號
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [-y, @modelcontextprotocol/server-filesystem, /Users/me/Documents]
    }
  }
}

快速驗證方法:把整份 JSON 貼到 jsonlint.com,或在終端機跑:

python3 -m json.tool ~/Library/Application\ Support/Claude/claude_desktop_config.json

沒有錯誤它會格式化印出 JSON;有錯誤會顯示 Expecting value: line X column Y 之類的訊息加上行號,一眼就找到問題在哪。

坑 2:改完設定忘記完全重啟,Claude Desktop 沒讀到新設定

MCP 設定是啟動時讀一次,修改設定檔後必須完全退出再重開才會生效。macOS 要按 Cmd+Q(左上角紅點只是縮小視窗,程式還在跑);Windows 要從系統匣的 Claude 圖示完全退出。

判斷有沒有真正重啟:打開 Claude Desktop 後立刻看有沒有錘子 icon。有 → server 成功啟動;沒有 → 不是設定有問題,就是沒有真正重啟。養成習慣:每次改完設定,先確認工作列/程式塢裡 Claude 的圖示真的消失了,再重新打開。

坑 3:路徑拼錯或資料夾不存在

Filesystem server 啟動時會嘗試掃描你指定的路徑,如果路徑不存在就會失敗,錘子 icon 不出現或點開是空的。常見的錯誤像:

Error: ENOENT: no such file or directory, scandir '/Users/myname/Doucments'

(Documents 拼成 Doucments。只差一個字母,肉眼很難發現)

解法:先在終端機確認路徑存在:

ls /Users/yourname/Documents

能列出內容再把一模一樣的字串貼進設定檔。macOS 的小技巧:在 Finder 裡把資料夾拖進終端機視窗,它會自動貼出完整的絕對路徑,省去手打出錯的機會。

坑 4:Claude Desktop 找不到 npx,server 無聲無息啟動失敗

Claude Desktop 是用它自己的環境啟動 MCP server,這個環境的 PATH 不一定和你終端機的 PATH 一樣。即使你在終端機跑 npx --version 完全正常,Claude Desktop 有時還是找不到 npx——特別是用 nvm、asdf、或 Homebrew 裝 Node.js 的情況下。

解法:在設定檔裡把 "command" 改成 npx 的完整絕對路徑:

# 在終端機查 npx 的完整路徑
which npx
# 輸出範例:
# /opt/homebrew/bin/npx       ← Homebrew 裝的
# /Users/yourname/.nvm/versions/node/v22.0.0/bin/npx  ← nvm 裝的

把查到的完整路徑填進設定檔的 command:

{
  "mcpServers": {
    "filesystem": {
      "command": "/opt/homebrew/bin/npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Documents"
      ]
    }
  }
}

作業

1. 主線任務:照著這堂課的步驟,在你自己的電腦裝好 filesystem server。成功標準:錘子 icon 出現,點開能看到工具清單。
2. 讀寫驗證:開一個新對話,叫 Claude 在你指定的資料夾建立一個 mcp-practice.txt,內容寫上今天日期和你的名字。跑完後用 Finder 打開確認檔案真的建出來了、內容是對的。
3. 選做挑戰:在 args 裡加第二個資料夾路徑,然後叫 Claude 把第一個資料夾裡的 mcp-practice.txt 複製到第二個資料夾。觀察它怎麼用 read_file 配合 write_file 完成這個任務。

下一課預告

裝好 filesystem server 之後,你大概會開始想:讀寫本機資料夾只是 MCP 能做的一小塊。Notion、GitHub、Slack、Figma……每一個你每天在用的工具,都有對應的官方或社群 MCP Server。但 2026 年官方 registry 已有超過 9,600 筆紀錄,光是挑就能挑死人。

第 3 課《實用組合:打造你的日常 MCP 工具組》帶你從幾千個 server 裡篩出真正有用的前幾名,解釋怎麼把多個 server 同時設進同一份設定檔,以及不同 server 搭配起來能做到什麼事。你這堂裝好的 filesystem 基礎,下一課就會用上。