Provides tools for interacting with a Synology NAS, including reading and searching files, retrieving system, resource, and storage information, managing Docker containers, and controlling Download Station download tasks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Synology NAS MCP show me the current CPU and memory usage on the NAS"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Self-hosted MCP access to Synology NAS files, monitoring, containers and downloads.
Synology NAS 的自架 MCP 服務。在 Container Manager 執行，透過 MCP 客戶端讀取文件、查詢 NAS 狀態，並按需啟用容器及下載操作。支援 Streamable HTTP、stdio，以及可選的 OpenAI Secure MCP Tunnel。
Alpha：具備自動化測試；Synology DSM／套件相容性及 ChatGPT 連通仍需實機驗證。 本專案為社群專案，與 Synology、OpenAI 沒有隸屬關係。
工具 | 用途 | 啟用條件 |
| 列出資料夾、分頁 | 唯讀資料夾掛載 |
| 遞迴比對檔名，不分大小寫 | 唯讀資料夾掛載 |
| 讀取 UTF-8、PDF、DOCX 文字 | 唯讀資料夾掛載 |
| NAS 型號、版本、溫度等 | DSM 帳戶 |
| CPU、記憶體、網路、磁碟 I/O | DSM 帳戶 |
| 磁碟及儲存空間狀態 | DSM 帳戶 |
| 容器狀態摘要 | DSM 帳戶及 Container Manager |
| 下載任務摘要 | DSM 帳戶及 Download Station |
| 啟動、停止、重啟指定容器 | 操作開關及精確名稱清單 |
| 在固定目的地建立下載 | 操作開關；受限 magnet URI |
| 暫停、繼續目的地範圍內的任務 | 操作開關及固定目的地 |
PDF 支援文字層；DOCX 擷取主文件段落。沒有 OCR、全文索引或排版還原。檔案名稱和內容以原文回傳。容器工具不回傳環境變數；下載摘要不回傳來源 URL 或帳密。
Related MCP server: Synology MCP Server
需要支援 Container Manager／Docker Compose 的 NAS。此專案使用 Linux 的安全檔案開啟介面；本機開發亦支援 macOS。
下載或 clone 本倉庫，放到 NAS 的專案資料夾：
git clone https://github.com/miku233333/synology-nas-mcp.git
cd synology-nas-mcp
cp .env.example .env
chmod 600 .env建立專用共享資料夾，例如 /volume1/AI-Share，放入可讓 MCP 客戶端讀取的文件。在 .env 設定：
NAS_SHARE_PATH：現有資料夾的絕對路徑。
NAS_UID、NAS_GID：有權讀取該資料夾的 DSM 使用者數字 UID/GID，可用 id 使用者名稱 查詢。不要用 root。
MCP_AUTH_TOKEN：自行執行 openssl rand -hex 32 產生，填入結果。
Token、密碼及 .env 留在自己的 NAS；不要加入 Git。含 $ 或 # 的 .env 密碼請使用單引號包住。
啟動：
docker compose up -d --build
docker compose ps亦可在 DSM Container Manager → 專案 匯入此資料夾及 compose.yaml。首版由原始碼建置，未提供預先發佈的專案 image。
預設只掛載選定資料夾，容器內路徑是 /data，讀取請用 報告.pdf 等相對路徑。掛載及容器檔案系統均為唯讀。預設不發佈主機連接埠；服務只供同一 Docker 網路內的客戶端或 Tunnel 連線。
OpenAI Secure MCP Tunnel 是可選的傳輸元件；MCP 本身不需要 OpenAI API key，也不依賴任何專案維護者的伺服器。
在 OpenAI Platform Tunnels 建立 Tunnel，取得 tunnel_id。執行 Tunnel 的 API key 需要 Tunnels Read + Use；建立 Tunnel 另需 Manage。
把 Tunnel 關聯到要使用的 ChatGPT workspace。在 .env 填入自己的 CONTROL_PLANE_API_KEY、CONTROL_PLANE_TUNNEL_ID。這裡使用 OpenAI Platform 的 runtime API key，與 MCP_AUTH_TOKEN 不同。
啟動可選 profile：
docker compose --profile chatgpt up -d --build
docker compose --profile chatgpt ps在 ChatGPT 啟用 Developer mode，前往 Plugins 建立連接，選 Connection → Tunnel，選取該 Tunnel。本部署沒有使用者層 OAuth；如出現認證選項，選 No Authentication。Tunnel 與 NAS MCP 之間仍使用設定好的 Bearer token。
在新對話選取此 MCP，先測試：「列出 NAS 分享資料夾」，再讀取一份已知測試文件，比對回傳內容。管理操作另外驗證。
Tunnel 由 NAS 主動向 OpenAI 連線；NAS 須能連到 api.openai.com:443。不需要將 DSM 或 MCP 公開到網際網路。Mac 關機不影響 NAS 上的服務。
ChatGPT 功能取決於帳戶、Developer mode 與 workspace 權限。官方開發者文件和 Help Center 對個人方案的寫入支援描述不完全一致，請以實際帳戶驗證，不把建立連接視為所有操作已可用。
參考：Secure MCP Tunnel、Developer mode、Help Center。
stdio 不需要 HTTP token：
uv sync --locked
MCP_TRANSPORT=stdio NAS_DATA_ROOT=/path/to/shared-folder uv run synology-nas-mcpHTTP 客戶端在同一 Docker 網路連到 http://nas-mcp:8000/mcp，加上 Authorization: Bearer <MCP_AUTH_TOKEN>。如需從 NAS 主機本地測試，可建立 compose.local.yaml：
services:
nas-mcp:
ports:
- "127.0.0.1:8000:8000"docker compose -f compose.yaml -f compose.local.yaml up -d此 HTTP token 是私有部署的服務認證，沒有實作 ChatGPT 公開 MCP 所需的 OAuth 流程。若要提供公共 HTTPS 入口，必須另行加入合適的 OAuth gateway、TLS 及存取控制；不可直接公開此範例。
只使用檔案功能時，留空所有 DSM_* 即可。要查詢 DSM，填入完整的三個設定：
DSM_URL=https://nas.example.net:5001
DSM_USERNAME=mcp-service
DSM_PASSWORD='your-local-password'建立專用 DSM 帳戶，僅授予所需套件及資料權限。套件或 DSM API 若要求帳戶沒有的權限，工具會回報錯誤；不同 DSM 版本的系統／Container Manager API 可能需要管理員權限，本專案不會提升帳戶權限。不要以主帳戶作為服務帳戶。
目前不支援互動式 2FA 登入。啟用 2FA 的帳戶會無法登入；不要為此停用日常管理員帳戶的 2FA。部署者須自行選擇符合其安全政策的服務帳戶安排。
DSM_URL 必須使用 HTTPS 並通過憑證驗證。私人 CA 可透過唯讀掛載 CA 檔案，再設定 DSM_CA_BUNDLE=/certs/ca.pem；此路徑必須是容器內的路徑。
NAS_ENABLE_CONTAINER_ACTIONS=true
NAS_ALLOWED_CONTAINERS=demo-web,media-indexer只接受清單中完全相同的名稱及 start、stop、restart。讀取檔案仍維持唯讀。不要將 Tunnel、MCP 本身或關鍵網路容器放入操作清單。
NAS_ENABLE_DOWNLOAD_ACTIONS=true
NAS_DOWNLOAD_DESTINATION=Downloads/MCP目的地使用 Download Station 的 共享資料夾/子資料夾 格式，必須存在且服務帳戶有權寫入。對話不能更改目的地；暫停／繼續前會核對任務目的地。
首版建立下載只接受具有有效 BTIH hash 的 magnet URI，可附 dn 名稱。其他參數（包括 tracker、web seed URL）及 HTTP／HTTPS 下載不支援。操作工具回覆 accepted 只表示 DSM 接受請求，容器或下載結果須再查實際狀態。
設定 | 預設值 | 說明 |
|
| 單份檔案最多 2 MiB |
|
| 回傳文字字數上限 |
|
| 每次搜尋／列目錄的掃描上限 |
|
| 本機亦可用 |
| 必填 | HTTP 服務 token，至少 32 個可見 ASCII 字元 |
| localhost／Docker 服務名 | 直接執行時的允許 Host 清單 |
完整部署參數見 .env.example。直接執行服務時，MCP_AUTH_TOKEN_FILE、DSM_PASSWORD_FILE 可從 secret 檔案讀取；使用 Compose secrets 需在自己的 Compose override 掛載檔案並配置這些變數。
禁止絕對路徑、父目錄越界、符號連結、FIFO 及裝置檔案。
PDF 最多解析 200 頁，頁面與資源內容累計解碼上限 4 MiB；含大型圖片的 PDF 也可能超出此限制。DOCX 最多 1,024 個 ZIP entries、總展開量 8 MiB、主文件 XML 4 MiB。每個程序一次解析一份文件。
路徑最多 64 層；搜尋遇到更深子目錄會略過並回報 truncated。
回覆包含 truncated 時，表示結果不完整；縮小資料夾或查詢範圍。
Compose 限制 MCP 容器記憶體 256 MiB、CPU 1 核；高壓縮或複雜文件仍可能觸及容器限額。
每個容器日誌最多約 30 MiB；唯讀檔案不建立額外副本、索引或備份。
DSM 寫入失敗或逾時不會自動重播；應先查實際狀態，再由使用者決定重試。
工具的確認提示取決於 MCP 客戶端；伺服器上的操作開關及範圍檢查才是強制權限界線。
檔案與工具回覆會交給選用的 AI 服務。請只掛載準備分享的資料夾。詳見 SECURITY.md。
uv sync --locked
uv run ruff check .
uv run ruff format --check .
uv run pytest -q
docker build -t synology-nas-mcp:local .測試涵蓋檔案越界／符號連結、格式擷取及大小限制、HTTP 認證與 MCP 呼叫、DSM session、操作權限和輸出過濾。DSM 使用模擬 HTTP 回覆；測試通過不代表特定 NAS／ChatGPT 已連通。
程式使用官方 MCP Python SDK，依賴由 uv.lock 鎖定。升級後重建容器；回退可 checkout 前一個已驗證的 Git commit 再重建。不要清除既有可回退 image，直到新版本驗證通過。
DSM 協定參考 Synology 官方 DSM Login Web API Guide 與 Download Station Web API Guide。
This is a community-maintained alpha, not an official Synology integration. Clone the repository, copy .env.example to .env, set an existing NAS_SHARE_PATH, a non-root UID/GID with read access, and a random MCP_AUTH_TOKEN. Run docker compose up -d --build.
Files are mounted read-only. DSM credentials are optional; container and download actions require explicit switches and scopes. The optional chatgpt Compose profile runs OpenAI's Secure MCP Tunnel using your own Platform key and tunnel ID. It does not require public NAS ports. HTTP uses a private Bearer token; stdio also works. Public OAuth hosting is outside this deployment.
Reads support UTF-8 text and text extraction from PDF/DOCX, with bounded output and no OCR. Search matches filenames. Download creation accepts only restricted BTIH magnet links. NAS compatibility and ChatGPT account access require live validation. Run the commands above for local tests.
List a shared directory using a relative path and bounded pagination.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | . | |
| limit | No | ||
| offset | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds 'bounded pagination' and 'relative path' which give some behavioral context, but it does not disclose details like recursive listing, hidden file inclusion, or error behavior. Given the annotation coverage, this is acceptable but not rich.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core action ('List a shared directory') and then adds key modifiers ('relative path', 'bounded pagination'). Every word earns its place, and there is no fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, no nested objects, and only three parameters with defaults, the tool is relatively simple. The description covers the purpose and pagination, but it does not mention the response format, whether listing is recursive, or any special behaviors. For a read-only listing tool, this is adequate but not fully complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the burden. It clarifies that 'path' is relative, which is not in the schema, and 'bounded pagination' implies that limit and offset control the result set. However, it does not explain the defaults or behavior of each parameter in detail, leaving some ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('a shared directory'), with additional specificity about using a relative path and bounded pagination. This distinguishes it from sibling tools like search_files (which searches) and read_file (which reads content) without needing to open the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus the alternatives. It does not mention search_files for searching or read_file for reading file contents, nor does it state any exclusion criteria. An agent must infer usage from the name and basic description alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read bounded text from a shared text, PDF or DOCX file. No OCR.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral context: 'bounded text' suggests a limit on the amount read, and 'No OCR' clarifies that scanned/image-based content won't be processed. These details go beyond annotations and are not contradictory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence with minimal waste. The core action ('Read') and key constraints ('bounded text', 'No OCR') are front-loaded, making it easy to parse. It is appropriately concise for a simple tool, though slightly more detail could be added without clutter.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with one parameter and no output schema, the description covers the fundamental purpose and a key limitation. However, 'bounded' is ambiguous (what is the limit?) and error behavior or return format is not mentioned. Given read-only annotations cover safety, the description is mostly adequate but leaves notable gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description should clarify the meaning of 'path', but it only implies it points to a shared file of the listed types. It does not specify whether the path is relative, absolute, or how it should be formatted. The description fails to compensate for the missing schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Read') and resource ('shared text, PDF or DOCX file'), and adds scoping with 'bounded text' and an explicit exclusion ('No OCR'). This clearly differentiates it from sibling tools list_files and search_files, which serve listing and searching rather than content retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The purpose implies it is for reading file content, but the description does not explicitly state when to choose this over list_files or search_files, nor does it mention prerequisites or when not to use it (e.g., for large files or scanned images). The guidance is implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find files by name inside the shared directory; not a full-text search.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | . | |
| limit | No | ||
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already communicate read-only, non-destructive behavior, so the bar is lower. The description adds useful context about the shared-directory scope and non-full-text behavior, but it does not clarify recursion, case sensitivity, or hidden-file handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence with no filler. The core purpose is front-loaded, and the negative qualifier is placed second for immediate disambiguation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given three undocumented parameters, no output schema, and available sibling tools, the description is too sparse. It fails to explain path and limit semantics, the type of results returned, or how this relates to list_files and read_file beyond the abstract distinction.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, but it only hints at the meaning of query via 'find files by name.' It says nothing about path or limit, leaving two of three parameters effectively undocumented.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'Find files by name inside the shared directory.' It also draws a clear boundary with 'not a full-text search,' making the tool's scope easily distinguishable from list_files and read_file.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool by saying it finds files by name, and it offers an exclusion by stating it is not full-text search. However, it never names sibling alternatives or explicitly says when to prefer list_files or read_file.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0list_filesread_filesearch_filesScored across 3 tools
Each tool has a clearly distinct purpose: listing directory contents, searching by filename, and reading file contents. There is no overlap or confusion between the three operations.
All tool names follow the same verb_noun snake_case pattern (list_files, search_files, read_file). The convention is perfectly consistent and predictable.
Three tools is a well-scoped set for a focused read-only file access server. Each tool covers a distinct necessary action and none are redundant.
The server covers reading and locating files, but lacks write/upload, delete, move, or binary file handling. For a NAS-oriented server these are notable gaps, though basic read-only workflows are supported.
Remote MCP server to read and manage your Atako AI agents, messages, files, and integrations.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
Hosted MCP server connecting AI assistants to 9,000+ apps and 40,000+ actions via Zapier.
Remote MCP server for supportsheep: run AI interviews and manage support content for your blog.
