synology-office-mcp

Visit landing page.

A self-hosted Model Context Protocol server that exposes Synology Drive, Spreadsheet, MailPlus, and Calendar as structured tools for AI agents (Claude Code, Claude Desktop, GoClaw, or any MCP-compatible client).

Wraps the official Synology Office Suite REST API. LAN-only by default — no data leaves your network unless you explicitly opt in.

v0.3.0 milestone — All four modules (Drive, Spreadsheet, MailPlus, Calendar) implemented and unit-tested with MSW mocks. Smoke tests against a real DSM 7.2.2 NAS are needed before declaring v1.0.0 production-ready. See CHANGELOG for details.

Table of Contents

• Features

• Requirements

• Install

• Quick Start

• Configuration

• Tool Reference

• Connecting an MCP Client

• Transport Modes

• Architecture

• Security Model

• Development

• Testing

• Documentation

• Contributing

• License

Features

Modules not included (no public API yet): Synology Docs, Synology Slides.

Design principles

• Self-hosted, LAN-only by default — TLS verification on, SSE bound to 127.0.0.1 unless MCP_AUTH_TOKEN is set

• No third-party MCP middlemen — every Synology call goes through the official REST API

• Read-heavy, safe writes — destructive operations require an explicit confirm: true parameter

• Stateless tool calls — each MCP invocation is independent; session/token lifecycle is internal

• Single binary — compiled ESM TypeScript, deployable as node dist/index.js

Requirements

Verify your DSM build: Control Panel > Info Center > DSM Version. Must be ≥ 72806.

Install

Global CLI (npm/pnpm):

npm install -g synology-office-mcp
# or
pnpm add -g synology-office-mcp

From source:

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

Quick Start

1. Deploy the Spreadsheet API container on your NAS

The Spreadsheet module talks to Synology's official synology/spreadsheet-api container — not to DSM directly. Skip this step only if you set SYNO_ENABLE_SPREADSHEET=false.

In Container Manager (DSM 7.2+) or via SSH:

# Pull the official image
sudo docker pull synology/spreadsheet-api:latest

# Run (port 3000 is the container default; map to whatever you prefer on the host)
sudo docker run -d \
  --name synology-spreadsheet-api \
  --restart unless-stopped \
  -p 3000:3000 \
  synology/spreadsheet-api:latest

Then in DSM:

• Control Panel → Application Privileges → Synology Office — make sure the DSM account you'll use has access.

• Control Panel → Security → Account — whitelist the Docker bridge subnet so the container's back-call to DSM is not auto-blocked.

Tip — homelab DSM with self-signed cert: the container ships without DSM's CA and will fail HTTPS verification on its /authorize back-call. Point the back-call at DSM's HTTP port via SYNO_SS_DSM_HTTPS=false + SYNO_SS_DSM_PORT=5000 (see env table below). Your MCP → DSM connection stays on HTTPS.

2. Configure environment variables

Copy .env.example to .env and edit, or export directly:

# ---- DSM connection (required) ----
export SYNO_HOST=192.168.1.100        # NAS hostname or IP
export SYNO_PORT=5001                  # 5000 = HTTP, 5001 = HTTPS
export SYNO_HTTPS=true                 # Use HTTPS for MCP → DSM
export SYNO_IGNORE_CERT=false          # true ONLY for trusted self-signed cert
export SYNO_USERNAME=your_nas_user
export SYNO_PASSWORD=your_nas_password

# ---- Spreadsheet API container (required if Spreadsheet module enabled) ----
export SYNO_SS_HOST=192.168.1.100      # Host running synology/spreadsheet-api
export SYNO_SS_PORT=3000               # Container port (default 3000)
export SYNO_SS_HTTPS=false             # Container default is plain HTTP

# ---- Spreadsheet container's back-call to DSM (advanced) ----
# Override only when the container can't TLS-verify DSM (e.g. self-signed cert).
# All three default to the matching SYNO_* value if left unset.
export SYNO_SS_DSM_HOST=192.168.1.100  # DSM host the container reaches
export SYNO_SS_DSM_PORT=5000           # Use DSM HTTP port to bypass cert issues
export SYNO_SS_DSM_HTTPS=false         # false → skip TLS verify on back-call

2FA accounts: the Spreadsheet /authorize endpoint does not accept OTP. Create a dedicated DSM service account without 2FA for unattended automation. Leave SYNO_OTP_CODE empty.

3. Run the MCP server

# stdio mode (default — used by Claude Desktop / Claude Code)
node dist/index.js

# Or via the global CLI after `npm install -g synology-office-mcp`
synology-mcp

The server prints a startup banner and waits for MCP JSON-RPC messages on stdin/stdout. See Configuration for the full env reference and Connecting an MCP Client for client wiring.

Configuration

All configuration is via environment variables, validated by Zod at startup. See .env.example for the full list with inline documentation.

Required

Common optional

Warning: SYNO_IGNORE_CERT=true disables MITM protection. Only use it on trusted home networks with self-signed certs you control.

Tool Reference

Full table of all 39 tools with input schemas: tool-reference.md.

Quick summary by module:

• Drive (11): drive_list_files, drive_search_files, drive_get_file_info, drive_download_file, drive_upload_file, drive_create_folder, drive_move_file, drive_delete_file, drive_get_sharing_link, drive_list_labels, drive_add_label

• Spreadsheet (13): spreadsheet_list, spreadsheet_register, spreadsheet_get_info, spreadsheet_read_sheet, spreadsheet_get_styles, spreadsheet_write_cells, spreadsheet_append_rows, spreadsheet_batch_update, spreadsheet_add_sheet, spreadsheet_rename_sheet, spreadsheet_delete_sheet, spreadsheet_create, spreadsheet_export

• MailPlus (6): mailplus_list_folders, mailplus_list_messages, mailplus_get_message, mailplus_send_message, mailplus_move_messages, mailplus_mark_messages

• Calendar (7): calendar_list_calendars, calendar_list_events, calendar_get_event, calendar_create_calendar, calendar_create_event, calendar_update_event, calendar_delete_event

Connecting an MCP Client

Claude Desktop (claude_desktop_config.json)

{
  "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"
      }
    }
  }
}

See examples/claude-desktop-config.json for the complete snippet.

Claude Code

claude mcp add synology-office -- node /path/to/synology-office-mcp/dist/index.js

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

See examples/claude-code-add.sh for the full command with env vars.

GoClaw

See examples/goclaw-mcp.json. Start the server in SSE mode first (see Transport Modes).

Transport Modes

stdio (default)

The default mode. The process communicates via stdin/stdout — used by Claude Desktop and Claude Code.

node dist/index.js
# or: MCP_TRANSPORT=stdio node dist/index.js

SSE (Server-Sent Events)

Used for multi-client setups and GoClaw integration.

MCP_TRANSPORT=sse \
MCP_SSE_HOST=127.0.0.1 \
MCP_SSE_PORT=3100 \
MCP_AUTH_TOKEN="$(openssl rand -hex 32)" \
node dist/index.js

Clients connect to http://<host>:3100/sse with Authorization: Bearer <token>.

Security: The server refuses to start when SSE is bound to a non-loopback address without MCP_AUTH_TOKEN. See security-model.md.

Architecture

┌─────────────────────────────────────────────────┐
│        MCP Client (Claude / GoClaw / …)          │
└──────────────────────┬──────────────────────────┘
                       │ MCP (JSON-RPC 2.0, stdio | SSE)
┌──────────────────────▼──────────────────────────┐
│            synology-office-mcp                   │
│                                                  │
│  ┌─────────────┐  ┌──────────────────────────┐  │
│  │  MCP Layer  │  │  Synology API Client      │  │
│  │  Tools      │  │  AuthManager + TokenCache │  │
│  │  Resources  │  │  BaseClient (HTTP)        │  │
│  │  Prompts    │  │  Drive / Sheet / Mail / … │  │
│  └──────┬──────┘  └────────────┬─────────────┘  │
└─────────┼────────────────────────┼──────────────┘
          │                        │ HTTPS
┌─────────▼────────────────────────▼──────────────┐
│       Synology NAS (DSM 7.2.2 + Office Suite)   │
└─────────────────────────────────────────────────┘

See integration-guide.md for client wiring across MCP-compatible agents.

Security Model

• TLS verification on by default. SYNO_IGNORE_CERT=true is opt-in and logged at startup.

• Credentials never appear in URLs. Login uses POST with form body; session id (sid) forwarded via Cookie: id=….

• SSE binds loopback by default. Server refuses to start when SSE is bound to non-loopback without MCP_AUTH_TOKEN.

• Sensitive values are redacted in logs via src/utils/redact.ts.

• Path traversal is blocked at tool boundary by src/utils/path-guard.ts.

• Destructive operations require confirm: true in the tool input.

Detailed threat model: security-model.md. Vulnerability disclosure: SECURITY.md.

Development

pnpm install            # install deps
pnpm dev                # build + watch
pnpm typecheck          # tsc --noEmit
pnpm lint               # eslint src --max-warnings 0
pnpm format             # prettier --write
pnpm test               # vitest run
pnpm test:coverage      # vitest run --coverage
pnpm build              # tsup → dist/

Pre-commit hooks (Husky + lint-staged) run typecheck, lint, and Prettier on staged files.

See CONTRIBUTING.md for the full contributor workflow.

Testing

pnpm test               # unit only
SMOKE_TEST=1 \
  SYNO_HOST=192.168.1.100 \
  SYNO_USERNAME=user \
  SYNO_PASSWORD=pass \
  pnpm test             # include smoke tests (requires real NAS)

See examples/smoke-test.ts for a standalone runnable smoke script.

Documentation

Contributing

PRs and issues are warmly welcomed — see CONTRIBUTING.md. For non-trivial changes, please open an issue first to discuss the approach.

This project follows Conventional Commits and Semantic Versioning.

License

MIT © 2026 Tien Chu — <chutien@gmail.com>

Synology, Synology Drive, Synology Office, MailPlus, and Synology Calendar are trademarks of Synology Inc. This project is an independent open-source client and is not affiliated with or endorsed by Synology Inc.