Bỏ qua tới nội dung
Agent Skill Hub
EN
Track 04 · Hướng dẫn

Kết nối với MCP server cục bộ

Mở rộng Claude Desktop bằng MCP server cục bộ để truy cập hệ thống file và các tích hợp khác.

Cơ bản@shine19049 phút đọc

Bài này hướng dẫn bạn kết nối Claude Desktop với một MCP server chạy trên máy, lấy Filesystem Server làm ví dụ.

Model Context Protocol (MCP) server mở rộng khả năng (capability) của ứng dụng AI bằng cách cho truy cập an toàn, có kiểm soát vào resource và tool cục bộ. Nhiều client hỗ trợ MCP, mở ra nhiều khả năng tích hợp (integration) trên các nền tảng và ứng dụng khác nhau.

Hướng dẫn này minh hoạ cách kết nối với MCP server cục bộ, dùng Claude Desktop làm ví dụ, một trong nhiều client hỗ trợ MCP. Dù chúng ta tập trung vào cách Claude Desktop hiện thực, các khái niệm áp dụng rộng cho những client tương thích MCP khác. Cuối bài, Claude sẽ tương tác được với file trên máy bạn: tạo tài liệu mới, sắp xếp thư mục và tìm kiếm trong hệ thống file, mỗi hành động đều cần bạn cho phép rõ ràng.

Claude Desktop tích hợp filesystem, hiển thị các khả năng quản lý file

Yêu cầu trước

Trước khi bắt đầu, hãy đảm bảo máy bạn đã cài:

Claude Desktop

Tải và cài Claude Desktop cho hệ điều hành của bạn. Claude Desktop có cho macOS và Windows.

Nếu đã cài Claude Desktop, hãy kiểm tra bạn đang chạy bản mới nhất bằng cách bấm menu Claude và chọn "Check for Updates..."

Node.js

Filesystem Server và nhiều MCP server khác cần Node.js để chạy. Kiểm tra Node.js bằng cách mở terminal hoặc command prompt và chạy:

bash
node --version

Nếu chưa cài Node.js, tải tại nodejs.org. Nên dùng bản LTS (Long Term Support) để ổn định.

Hiểu về MCP server

MCP server là chương trình chạy trên máy bạn và cung cấp các khả năng cụ thể cho Claude Desktop qua một giao thức chuẩn hoá. Mỗi server cung cấp các tool mà Claude có thể dùng để thực hiện hành động, khi bạn đồng ý. Filesystem Server mà chúng ta sẽ cài cung cấp các tool để:

  • Đọc nội dung file và cấu trúc thư mục
  • Tạo file và thư mục mới
  • Di chuyển và đổi tên file
  • Tìm file theo tên hoặc nội dung

Mọi hành động đều cần bạn phê duyệt rõ ràng trước khi thực thi, nhờ đó bạn giữ toàn quyền kiểm soát những gì Claude được truy cập và sửa đổi.

Cài Filesystem Server

Quá trình này là cấu hình Claude Desktop để tự khởi động Filesystem Server mỗi khi bạn mở ứng dụng. Cấu hình nằm trong một file JSON cho Claude Desktop biết cần chạy server nào và kết nối với chúng ra sao.

Bước 1: Mở Settings của Claude Desktop

Bắt đầu bằng việc mở phần cài đặt của Claude Desktop. Bấm menu Claude trên thanh menu của hệ thống (không phải phần cài đặt bên trong cửa sổ Claude) và chọn "Settings..."

Trên macOS, menu này nằm ở thanh menu phía trên:

Menu Claude Desktop với mục Settings

Thao tác này mở cửa sổ cấu hình Claude Desktop, tách biệt với phần cài đặt tài khoản Claude của bạn.

Bước 2: Vào Developer Settings

Trong cửa sổ Settings, chuyển sang tab "Developer" ở thanh bên trái. Mục này có các tuỳ chọn cấu hình MCP server và các tính năng khác cho lập trình viên.

Bấm nút "Edit Config" để mở file cấu hình:

Developer settings với nút Edit Config

Thao tác này tạo file cấu hình mới nếu chưa có, hoặc mở file cấu hình hiện có. File nằm tại:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Bước 3: Cấu hình Filesystem Server

Thay nội dung file cấu hình bằng cấu trúc JSON dưới đây. Cấu hình này bảo Claude Desktop khởi động Filesystem Server với quyền truy cập vào các thư mục cụ thể:

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

Thay username bằng tên người dùng thật trên máy bạn. Các đường dẫn trong mảng args xác định thư mục nào Filesystem Server được truy cập. Bạn có thể sửa các đường dẫn này hoặc thêm thư mục khi cần.

Bước 4: Khởi động lại Claude Desktop

Sau khi lưu file cấu hình, thoát hẳn Claude Desktop rồi mở lại. Ứng dụng cần khởi động lại để nạp cấu hình mới và chạy MCP server.

Khi khởi động lại thành công, bấm biểu tượng "Add files, connectors, and more /" ở góc dưới bên trái ô nhập hội thoại:

Giao diện Claude Desktop hiển thị biểu tượng MCP server

Bấm biểu tượng này, rê chuột tới "Connectors" rồi bấm "Manage connectors". Chọn "filesystem" trong danh sách connector để xem các tool sẵn có của Filesystem Server:

Các tool filesystem sẵn có trong Claude Desktop

Nếu Filesystem Server không kết nối được, xem mục Khắc phục sự cố bên dưới để biết các bước gỡ lỗi.

Dùng Filesystem Server

Khi Filesystem Server đã kết nối, Claude có thể tương tác với hệ thống file của bạn. Hãy thử các yêu cầu mẫu sau để khám phá khả năng của nó:

Ví dụ quản lý file

  • "Can you write a poem and save it to my desktop?": Claude sẽ sáng tác một bài thơ và tạo file văn bản mới trên desktop của bạn.
  • "What work-related files are in my downloads folder?": Claude sẽ quét thư mục downloads và nhận diện các tài liệu liên quan tới công việc.
  • "Please organize all images on my desktop into a new folder called 'Images'": Claude sẽ tạo một thư mục và chuyển các file ảnh vào đó.

Cách phê duyệt hoạt động

Trước khi thực hiện bất kỳ thao tác nào với hệ thống file, Claude sẽ xin bạn phê duyệt. Nhờ đó bạn giữ quyền kiểm soát mọi hành động:

Claude xin phê duyệt trước khi thực hiện thao tác file

Hãy xem kỹ từng yêu cầu trước khi phê duyệt. Bạn luôn có thể từ chối nếu không yên tâm với hành động được đề xuất.

Khắc phục sự cố

Nếu gặp vấn đề khi thiết lập hoặc dùng Filesystem Server, các cách sau giải quyết những lỗi thường gặp.

Server không hiện trong Claude / thiếu biểu tượng búa

  1. Khởi động lại hoàn toàn Claude Desktop
  2. Kiểm tra cú pháp file claude_desktop_config.json
  3. Đảm bảo các đường dẫn file trong claude_desktop_config.json hợp lệ, là đường dẫn tuyệt đối chứ không phải tương đối
  4. Xem log (mục bên dưới) để biết vì sao server không kết nối
  5. Trên dòng lệnh, thử chạy server bằng tay (thay username như bạn đã làm trong claude_desktop_config.json) để xem có lỗi gì không:
bash
npx -y @modelcontextprotocol/server-filesystem /Users/username/Desktop /Users/username/Downloads

Lấy log từ Claude Desktop

Log liên quan tới MCP của Claude.app được ghi vào các file log tại:

  • macOS: ~/Library/Logs/Claude
  • Windows: %APPDATA%\Claude\logs

Trong đó:

  • mcp.log chứa log chung về các kết nối MCP và lỗi kết nối.
  • Các file tên mcp-server-SERVERNAME.log chứa output stderr của server tương ứng. Server stdio có thể dùng stderr cho mọi log của nó, nên các file này không chỉ chứa lỗi.

Bạn có thể chạy lệnh sau để liệt kê log gần đây và theo dõi log mới (trên Windows, lệnh chỉ hiện log gần đây):

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

Lời gọi tool thất bại mà không báo lỗi

Nếu Claude thử dùng tool nhưng thất bại:

  1. Kiểm tra log của Claude để tìm lỗi
  2. Kiểm tra server của bạn build và chạy được mà không lỗi
  3. Thử khởi động lại Claude Desktop

Đã thử hết mà vẫn không được, phải làm sao?

Hãy xem hướng dẫn gỡ lỗi để có công cụ gỡ lỗi tốt hơn và chỉ dẫn chi tiết hơn.

Lỗi ENOENT và ${APPDATA} trong đường dẫn trên Windows

Nếu server đã cấu hình không nạp được và trong log có lỗi nhắc tới ${APPDATA} trong một đường dẫn, bạn có thể cần thêm giá trị đã khai triển của %APPDATA% vào khoá env trong claude_desktop_config.json:

json
{
  "brave-search": {
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-brave-search"],
    "env": {
      "APPDATA": "C:\\Users\\user\\AppData\\Roaming\\",
      "BRAVE_API_KEY": "..."
    }
  }
}

Sau khi sửa, mở lại Claude Desktop.

Bước tiếp theo

Giờ bạn đã kết nối thành công Claude Desktop với một MCP server cục bộ, hãy khám phá các lựa chọn sau để mở rộng thiết lập:

  • Khám phá các server khác: duyệt bộ sưu tập MCP server chính thức và do cộng đồng tạo để có thêm khả năng.
  • Tự xây server: tạo MCP server tuỳ chỉnh cho quy trình (workflow) và tích hợp cụ thể của bạn.
  • Kết nối với server từ xa: tìm hiểu cách kết nối Claude với MCP server từ xa để dùng tool và dịch vụ trên cloud.
  • Hiểu giao thức: tìm hiểu sâu hơn cách MCP hoạt động và kiến trúc của nó.

Nguồn

Viết thêm guide cho track này