Skip to main content
Glama
deenesjakoruzh
shunnnnn-png

synology-chat-hermes-mcp

by shunnnnn-png
OverviewSchemaRelated ServersScoreDiscussions
Python
Remote

synology-chat-hermes-mcp

English · 繁體中文

一个受限的 FastMCP HTTP 服务器，将固定的 Synology NAS SMB 共享以读/写文件工具的形式暴露给 AI 代理——内置严格的路径隔离、大小限制和活动内容拒绝机制。

最初作为家庭 Hermes 部署（控制代理 → MCP → SMB3 → NAS）的文件通道构建。适用于任何 MCP 客户端（Hermes、Claude 等）。

为什么存在

拥有文件访问权限的 AI 代理只有在访问受限时才是安全的。该服务器：

  • 将每个路径隔离到一个固定共享（NAS_SHARE）。在任何 SMB 调用之前拒绝路径穿越（..、绝对路径、符号链接/重解析点逃逸）。

  • 拒绝公网 WAN 服务器 — NAS_SERVER 必须是私有、链路本地或 Tailscale（100.64.0.0/10）字面 IP。拒绝 DNS 名称和公网 IP。

  • 从不存储凭据 — SMB 密码在启动时从 docker secret 文件中读取（NAS_PASSWORD_FILE），绝不从环境变量或代码中读取。

  • 阻止活动内容 — DOCX/XLSX/PDF 写入器仅生成已净化的文档；二进制上传会扫描宏、外部关系和脚本；拒绝扩展名/媒体类型不匹配。

  • 限制一切 — 文件大小、二进制大小、文档字符数、电子表格单元格、图像像素、搜索结果均有硬性限制。

  • 审计操作 — 每个变更操作都会追加到 JSONL 审计日志中。

Related MCP server: MCP File System Server

架构

Hermes (or any MCP client)
  → HTTP :8000/mcp (FastMCP, streamable HTTP)
    → NasService (validation, limits, audit)
      → SMBBackend (smbprotocol, SMB3, encryption+signing required)
        → Synology NAS share

工具

工具

说明

health

SMB3 连接检查

list_directory

列出共享下的目录

search_files

搜索路径下的文件名

read_file

读取大小受限的 UTF-8 文本文件

write_file

原子 UTF-8 写入（除非 overwrite，否则保护现有文件）

write_binary_file

经校验的 base64 写入（TXT/DOCX/XLSX/PDF/PNG/JPEG）

create_document

从标题 + 纯文本/类似 Markdown 的文本生成安全 DOCX

create_spreadsheet

安全 XLSX（拒绝公式）

create_pdf

静态 PDF（无脚本/链接/嵌入文件）

read_document

从 TXT/MD/CSV/JSON/YAML/DOCX/XLSX/PDF 提取文本

create_directory

创建目录（注意：一次创建一级 — parents=True 不可靠，见下文）

move_file

在共享内移动

get_file_info

不含内容的元数据

已知限制： create_directory 在 makedirs 之前校验父目录，因此如果多级路径的第一个段不存在，即使使用 parents=True 也会返回 not_found。请一次创建一级。

快速开始

cp .env.example .env   # set NAS_SERVER (Tailscale/private IP), NAS_USERNAME
# provide the SMB password as a docker secret:
printf '%s' 'YOUR_SMB_PASSWORD' > ./synology_password
chmod 600 ./synology_password

docker build -t nas-mcp .
docker run -d --name nas-mcp \
  --env-file .env \
  -v "$PWD/synology_password:/run/secrets/synology_password:ro" \
  -v nas-mcp-audit:/var/log/nas-mcp \
  -p 8000:8000 \
  nas-mcp

健康检查：

curl -X POST http://127.0.0.1:8000/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"health","arguments":{}}}'

Hermes MCP 配置

mcp_servers:
  nas-mcp:
    type: http
    url: http://nas-mcp:8000/mcp

运行测试

python -m nas_mcp.smoke   # exercises the full tool chain against the live share

环境变量参考

变量

必填

默认值

说明

NAS_SERVER

✅

—

仅限私有/Tailscale 字面 IP

NAS_SHARE

✅

—

固定共享名称，运行时强制

NAS_USERNAME

✅

—

共享级 SMB 用户

NAS_PASSWORD_FILE

/run/secrets/synology_password

Docker secret 路径

NAS_CONNECT_TIMEOUT_SECONDS

8

NAS_REQUIRE_ENCRYPTION

true

需要 SMB3 加密

NAS_REQUIRE_SIGNING

true

需要 SMB3 签名

NAS_AUDIT_LOG

/var/log/nas-mcp/audit.jsonl

NAS_MAX_FILE_BYTES

1048576

NAS_MAX_BINARY_FILE_BYTES

8388608

NAS_MAX_DOCUMENT_CHARS

100000

NAS_MAX_SPREADSHEET_CELLS

50000

NAS_MAX_DOCUMENT_EXPANDED_BYTES

67108864

NAS_MAX_IMAGE_PIXELS

25000000

NAS_MAX_SEARCH_ENTRIES

5000

NAS_MAX_SEARCH_RESULTS

100

NAS_MCP_HOST / NAS_MCP_PORT

0.0.0.0 / 8000

安全说明

  • SMB 密码是系统中唯一的机密，它仅存在于 docker secret 文件中。没有硬编码任何内容；除非机密的调优值外，.env 中不会以明文存储任何内容（且 .env 已被 git 忽略）。

  • 在生产环境中绑定到私有接口；不要公开暴露 :8000。

  • 共享名称和 SMB 用户是配置项（NAS_SHARE、NAS_USERNAME）——按部署设置即可；代码中不假设特定值。

许可证

MIT

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

  • MCP Files

    tspspi
    A
    license
    -
    quality
    C
    maintenance
    Provides a secure, constrained filesystem workspace for LLM agents to manage files, notes, and code artifacts via stdio or remote HTTP. It features granular access controls, including extension whitelisting, storage quotas, and immutable paths for safe automated file operations.
    BSD 3-Clause

  • MCP File System Server

    moaaz01
    F
    license
    -
    quality
    C
    maintenance
    A secure, sandboxed file system server that enables reading, writing, searching, and managing files through MCP-compatible AI clients with path traversal protection and size limits.

  • aily-local-file-mcp

    zhuxice-ctrl
    A
    license
    -
    quality
    B
    maintenance
    Exposes local file system operations to AI assistants via Streamable HTTP with security features like auth, path whitelisting, and audit logging.
    2,884
    1
    MIT

  • mcp-syncnology

    humyai99
    F
    license
    A
    quality
    B
    maintenance
    MCP server enabling AI agents to manage and monitor Synology NAS via official DSM API, including file operations, system stats, backups, downloads, and camera lists.
    15

View all related MCP servers

Related MCP Connectors

  • Frenchie

    OCR, transcription, file extraction, and image generation for AI agents via MCP.

  • putput-mcp

    File uploads for AI agents. Upload, list, and manage files. No signup required.

  • saagarpatel.dev Portfolio

    Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/shunnnnn-png/synology-chat-hermes-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server