Hướng dẫn cài đặt Synology Office MCP Server: cho Claude "đọc — ghi" trực tiếp NAS Synology

Nếu bạn đang dùng Synology NAS làm nơi lưu trữ chính cho tài liệu, bảng tính, email, lịch — và bạn cũng đang xài Claude Desktop hoặc Claude Code hằng ngày — thì sẽ có lúc bạn ước gì AI có thể đọc trực tiếp file .osheet trên Drive, gửi giúp một cái mail, tạo nhanh sự kiện trên Calendar, mà không phải copy-paste qua lại.

Đây chính là bài toán mà Synology Office MCP Server giải quyết. Trong bài này, mình sẽ đi từ đầu đến cuối: từ cài đặt, cấu hình, đến vài ví dụ thực tế gọi tool qua Claude.

Repo: https://github.com/vocweb/synology-mcp-server Trang chủ: https://synology-mcp-server.smb-base.com/ npm: synology-office-mcp

1. MCP là cái gì? Vì sao đáng quan tâm?

Model Context Protocol (MCP) là chuẩn mở do Anthropic khởi xướng, định nghĩa cách một AI agent giao tiếp với "công cụ bên ngoài" theo dạng JSON-RPC 2.0. Bạn cứ hình dung MCP server như một USB-hub: cắm vào Claude (hoặc bất kỳ MCP client nào), Claude sẽ thấy danh sách "tool" và biết cách gọi.

Khác với "plugin" cũ kiểu OpenAI, MCP là chạy local, tự host. Dữ liệu không phải đẩy qua đám mây thứ ba.

2. Synology Office MCP Server làm gì?

Nó hỗ trợ bộ API REST chính thức của Synology Office Suite (phát hành 02/2025) và tạo ra 37 tool trải đều bốn module:

Hai điểm an toàn quan trọng:

• LAN-only mặc định. SSE bind vào loopback, TLS bật.
• Confirm-required cho mọi thao tác phá huỷ. Xoá file, gửi mail, ghi đè cell đều phải có confirm: true. AI không thể vô tình xoá nhầm.

3. Yêu cầu hệ thống

Kiểm tra build DSM: Control Panel → Info Center → DSM Version.

4. Cài đặt server

4.1. Cài qua npm (khuyến nghị)

npm install -g synology-office-mcp
# hoặc
pnpm add -g synology-office-mcp

4.2. Hoặc build từ source

git clone https://github.com/vocweb/synology-mcp-server.git
cd synology-mcp-server
pnpm install && pnpm build

5. Triển khai container Spreadsheet API

Đây là bước dễ bị bỏ qua nhất. Module Spreadsheet không "nói chuyện" trực tiếp với DSM, mà phải thông qua container chính chủ synology/spreadsheet-api. Cần phải có container này để có bộ API chính chủ thì mới có thể tương tác được với các file trong Synology Office. Nếu bạn không cần Spreadsheet, đặt SYNO_ENABLE_SPREADSHEET=false và bỏ qua bước này.

Mở Container Manager trên DSM, hoặc SSH vào NAS:

sudo docker pull synology/spreadsheet-api:latest

sudo docker run -d \
 --name synology-spreadsheet-api \
 --restart unless-stopped \
 -p 3000:3000 \
 synology/spreadsheet-api:latest

Sau đó vào DSM:

• Control Panel → Application Privileges → Synology Office: cấp quyền cho user sẽ login.
• Control Panel → Security → Account: whitelist subnet của Docker bridge để DSM không tự động chặn.

Bẫy thường gặp: container không tin self-signed cert của DSM nên fail back-call HTTPS. Workaround: trỏ back-call qua HTTP port của DSM bằng SYNO_SS_DSM_HTTPS=false + SYNO_SS_DSM_PORT=5000.

6. Cấu hình biến môi trường

Tạo file .env (hoặc export trực tiếp):

# DSM connection — bắt buộc
export SYNO_HOST=192.168.1.100
export SYNO_PORT=5001
export SYNO_HTTPS=true
export SYNO_IGNORE_CERT=false
export SYNO_USERNAME=mcp_service_account
export SYNO_PASSWORD=your_strong_password

# Spreadsheet container
export SYNO_SS_HOST=192.168.1.100
export SYNO_SS_PORT=3000
export SYNO_SS_HTTPS=false

# Back-call DSM (workaround self-signed cert)
export SYNO_SS_DSM_HOST=192.168.1.100
export SYNO_SS_DSM_PORT=5000
export SYNO_SS_DSM_HTTPS=false

Lưu ý quan trọng về 2FA: endpoint /authorize của Spreadsheet không chấp nhận OTP. Hãy tạo một DSM service account riêng, tắt 2FA cho account đó, chỉ cấp quyền đủ dùng. Đừng dùng tài khoản admin cá nhân.

7. Khởi động server

Stdio mode (cho Claude Desktop / Claude Code)

synology-mcp
# hoặc
node dist/index.js

SSE mode (cho GoClaw, multi-client)

MCP_TRANSPORT=sse \
MCP_SSE_HOST=127.0.0.1 \
MCP_SSE_PORT=3100 \
MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
synology-mcp

Server sẽ in banner khởi động. Nếu thấy log Auth successful thì kết nối DSM đã ngon.

8. Kết nối Claude Desktop

Mở claude_desktop_config.json:

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

Thêm:

{
 "mcpServers": {
 "synology": {
 "command": "node",
 "args": [
 "<path_to_synology_mcp_server_source_code>/dist/index.js"
 ],
 "env": {
 "SYNO_HOST": "192.168.1.100",
 "SYNO_USERNAME": "dsm_username",
 "SYNO_PASSWORD": "dsm_password",
 "SYNO_SS_HOST": "192.168.1.100",
 "SYNO_SS_PORT": "3000",
 "SYNO_SS_HTTPS": "false",
 "SYNO_SS_DSM_HOST": "192.168.1.100",
 "SYNO_SS_DSM_PORT": "5001",
 "SYNO_SS_DSM_HTTPS": "false"
 }
 }
 }
}

Restart Claude Desktop. Vào chat, bấm icon "+" — bạn sẽ thấy tool của Synology.

9. Kết nối Claude Code

claude mcp add --scope user synology \
 -e SYNO_HOST=192.168.1.100 \
 -e SYNO_PORT=5001 \
 -e SYNO_HTTPS=true \
 -e SYNO_IGNORE_CERT=true \
 -e SYNO_USERNAME=dsm_username \
 -e 'SYNO_PASSWORD=dsm_password' \
 -e SYNO_SS_HOST=192.168.1.100 \
 -e SYNO_SS_PORT=3000 \
 -e SYNO_SS_HTTPS=false \
 -e SYNO_SS_DSM_HOST=192.168.1.100 \
 -e SYNO_SS_DSM_PORT=5000 \
 -e SYNO_SS_DSM_HTTPS=false \
 -- node <path_to_synology_mcp_server_source_code>/dist/index.js
 
claude mcp list

Xong. Mở session claude mới và gõ prompt /mcp sẽ liệt kê ra synology mcp.

10. Ví dụ sử dụng thực tế

Ví dụ 1 — Đọc bảng tính và tóm tắt

Prompt: "Đọc file /mydrive/reports/Q1-2026.osheet sheet Sales, tóm tắt 3 ý chính."

Claude sẽ tự gọi:

spreadsheet_list → tìm file
spreadsheet_get_info → lấy danh sách sheet
spreadsheet_read_sheet → đọc range A1:Z1000

Sau đó trả về tóm tắt mà không cần bạn upload gì cả.

Ví dụ 2 — Tạo loạt event từ bảng tính

Prompt: "Trong sheet Onboarding có cột Tên / Email / Ngày. Tạo cho tôi event 30 phút lúc 10h sáng cho mỗi dòng, mời đúng email, lịch Work."

Agent sẽ:

1. spreadsheet_read_sheet → lấy data
2. calendar_list_calendars → tìm cal_id của lịch Work
3. calendar_create_event cho từng dòng (kèm confirm: true sau khi bạn duyệt)

Ví dụ 3 — Triage email chưa đọc

Prompt: "Liệt kê 10 email INBOX chưa đọc gần nhất, soạn nháp trả lời cho cái nào liên quan đến hợp đồng."

mailplus_list_messages folder=INBOX unread_only=true limit=10
mailplus_get_message → đọc nội dung

Claude soạn nháp, bạn xem lại, rồi bảo "gửi giúp" — agent gọi mailplus_send_message với confirm: true.

Ví dụ 4 — Phân loại tài liệu cũ

Prompt: "Quét /mydrive/Archive, gắn label invoice cho các file PDF có chữ hoá đơn trong tên."

drive_search_files query="hoá đơn" extension="pdf"
drive_add_label → từng file

Ví dụ 5 — Backup nhanh

Prompt: "Xuất sheet Customers ra xlsx, trả base64 cho tôi."

spreadsheet_export format=xlsx → bạn nhận về base64, lưu local là xong.

11. Mẹo bảo mật

• Không dùng account admin. Tạo service account riêng, cấp đúng quyền cần thiết qua Application Privileges.
• Bật SYNO_IGNORE_CERT=false ở môi trường production. Chỉ tắt khi bạn thực sự kiểm soát self-signed cert của mình.
• SSE ra ngoài loopback bắt buộc có MCP_AUTH_TOKEN. Server sẽ refuse start nếu không có — đây là tính năng, không phải bug.
• Đừng commit .env. Repo đã add sẵn vào .gitignore.

12. Troubleshooting nhanh

Chi tiết tại troubleshooting.md.

13. Kết

Synology Office MCP Server cho bạn cách rẻ nhất, an toàn nhất để biến chiếc NAS đang chạy trong nhà thành "bộ não dữ liệu" cho AI agent. Dữ liệu không rời mạng nội bộ, code mã nguồn mở MIT, deploy chỉ một câu lệnh.

Nếu bạn dùng Synology hằng ngày, mình thật sự khuyến khích thử. PRs và issues đều được hoan nghênh trên GitHub.

Repo: https://github.com/vocweb/synology-mcp-server Trang chủ: https://synology-mcp-server.smb-base.com/

Chúc bạn cài đặt vui vẻ. Nếu có thắc mắc, comment bên dưới mình sẽ trả lời.