Bắt đầu với MCP Server cục bộ trên Claude Desktop

MCP server cục bộ là gì?

Model Context Protocol (MCP) là một giao thức mở giúp các ứng dụng AI kết nối với nguồn dữ liệu và công cụ bên ngoài. Một MCP server cục bộ là một chương trình chạy trên chính máy bạn, cung cấp cho Claude Desktop một bộ công cụ (tools) theo chuẩn chung. Ví dụ, Filesystem Server cho Claude đọc nội dung file, tạo file và thư mục, di chuyển, đổi tên và tìm kiếm file.

Khác biệt so với custom connector (bài sau): custom connector là server từ xa, được gọi từ hạ tầng đám mây của Anthropic. Còn server cục bộ chạy trên máy bạn và dùng mạng của máy bạn, nên truy cập được file và công cụ mà đám mây không thấy. Bạn có thể xem lại cách chọn giữa hai loại ở bài Khi nào dùng connector desktop vs web.

Cách 1: Cài bằng Desktop Extension (dễ nhất)

Desktop Extension đóng gói một MCP server cục bộ thành file .mcpb cài được bằng một cú bấm, giống như tiện ích trình duyệt. Bạn không phải sửa file JSON hay tự cài thư viện; Claude Desktop có sẵn môi trường Node.js bên trong.

Cài từ thư mục chính thức

1. Vào Settings → Desktop app, bấm Manage cạnh mục Extensions (giao diện cũ: Settings → Extensions).
2. Bấm Browse extensions, chọn một công cụ đã được Anthropic xem xét, rồi bấm Install.
3. Nhập các thiết lập được yêu cầu, ví dụ API key, ngay trong giao diện.
4. Extension tự có mặt trong các cuộc trò chuyện.

Cài file .mcpb tự có

1. Mở trang Extensions như trên, bấm Advanced settings và tìm mục Extension Developer.
2. Bấm Install Extension…, chọn file .mcpb và làm theo hướng dẫn.

Các trường được đánh dấu nhạy cảm (như API key) được mã hóa bằng kho bảo mật của hệ điều hành: Keychain trên macOS, Credential Manager trên Windows. Extension từ thư mục chính thức tự cập nhật; extension nhận riêng thì bạn phải tự cài bản mới.

Cách 2: Tự cấu hình bằng claude_desktop_config.json

Cách này hợp khi server bạn muốn dùng chưa có dạng extension. Ví dụ dưới đây theo hướng dẫn chính thức của modelcontextprotocol.io với Filesystem Server.

Chuẩn bị

• Claude Desktop bản mới nhất (menu Claude → Check for Updates…).
• Node.js, vì Filesystem Server chạy bằng Node. Kiểm tra bằng lệnh node --version; chưa có thì tải bản LTS ở nodejs.org.

Các bước

1. Mở Settings… từ 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ổ chat).
2. Chọn tab Developer và bấm Edit Config. File cấu hình sẽ được tạo nếu chưa có:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%Claudeclaude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json
3. Khai báo server trong khóa mcpServers. Ví dụ trên Windows (thay username bằng tên người dùng của bạn):

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

   Trong đó "filesystem" là tên hiển thị, npx dùng để chạy gói server, còn các đường dẫn cuối là những thư mục server được phép truy cập.
4. Lưu file, thoát hẳn Claude Desktop rồi mở lại để ứng dụng nạp cấu hình mới.

Kiểm tra server đã kết nối

1. Bấm nút + ở góc dưới bên trái ô nhập tin nhắn.
2. Di chuột tới Connectors, chọn Manage connectors.
3. Chọn filesystem để xem danh sách công cụ của server.

Bạn cũng có thể xem mục Local MCP servers trên trang Extensions (giao diện cũ: Settings → Developer), nơi hiển thị trạng thái kết nối và log.

Khi server không hiện hoặc không chạy

• Khởi động lại Claude Desktop hoàn toàn.
• Kiểm tra cú pháp JSON của file cấu hình (thiếu dấu phẩy, ngoặc là lỗi thường gặp).
• Dùng đường dẫn tuyệt đối, không dùng đường dẫn tương đối.
• Xem log: mcp.log ghi thông tin kết nối chung, còn mcp-server-TÊN.log ghi đầu ra lỗi của từng server. Thư mục log: ~/Library/Logs/Claude (macOS), %APPDATA%Claudelogs (Windows).
• Chạy thử lệnh server trực tiếp trong terminal để xem lỗi:

  npx -y @modelcontextprotocol/server-filesystem C:UsersusernameDesktop C:UsersusernameDownloads

• Trên Windows, nếu log báo lỗi ENOENT kèm ${APPDATA} trong đường dẫn, thêm giá trị đầy đủ của %APPDATA% vào khóa env của server, và đảm bảo npm đã được cài toàn cục (npm install -g npm).
• Với extension: cập nhật Claude Desktop, tải lại file nếu nghi bị hỏng, kiểm tra các trường bắt buộc và API key đã nhập đúng.

An toàn và quản trị

MCP server chạy với quyền tài khoản người dùng của bạn, nghĩa là nó làm được mọi thao tác file mà bạn làm được bằng tay. Chỉ cấp quyền cho những thư mục bạn chấp nhận để Claude đọc và sửa, và chỉ cài server từ nguồn tin cậy.

Với gói Team và Enterprise, Owner và Primary Owner có thể bật/tắt các extension công khai theo tiêu chuẩn bảo mật của tổ chức, và tải lên extension riêng để thành viên cài bằng một cú bấm.

Những điều bạn học được trong bài này

• MCP server cục bộ là chương trình chạy trên máy bạn, cung cấp công cụ cho Claude Desktop
• Cách dễ nhất là cài Desktop Extension (.mcpb) từ Settings → Desktop app → Extensions
• Cách thủ công: Settings → Developer → Edit Config, khai báo server trong mcpServers
• Luôn thoát hẳn và mở lại Claude Desktop sau khi sửa cấu hình
• Kiểm tra qua nút + → Connectors, và đọc log mcp.log khi gặp lỗi
• Server chạy với quyền của bạn, nên chỉ mở những thư mục cần thiết

Nguồn tham khảo: Getting Started with Local MCP Servers on Claude Desktop – Claude Help Center · Connect to local MCP servers – Model Context Protocol

Câu hỏi thường gặp