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

| Module | Tools | Key Capabilities | |---|---|---| | Drive | 11 | List / search / get info / download / upload / create folder / move / delete / share / labels | | Spreadsheet | 13 | List / register-by-name / get info / read sheet / get styles / write cells / append rows / batch update / add-rename-delete sheet / create / export | | MailPlus | 6 | List folders / list messages / get message / send / move / mark read-unread | | Calendar | 7 | List calendars / list events / get event / create calendar / create event / update event / delete event | | MCP Layer | — | Resources (file tree, mail folders, calendar list), prompts, stdio + SSE transports | | Security | — | TLS verify, path-guard, origin-guard, bearer-auth, log redaction, confirm-required writes |

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

| Component | Version | |---|---| | Node.js | >= 22.0.0 (ESM-only) | | pnpm | >= 9.0.0 (dev only) | | Synology DSM | 7.2.2 build 72806+ | | Synology Drive | 3.5.2+ | | Synology Office | 3.6.0+ (for Spreadsheet) | | Synology MailPlus | 3.3.1+ (requires MailPlus Server package) | | Synology Calendar | 2.5.3+ |

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

| Variable | Description | |---|---| | SYNO_HOST | NAS hostname or IP (192.168.1.100 or nas.local) | | SYNO_USERNAME | DSM account username | | SYNO_PASSWORD | DSM account password (use an app-specific password if 2FA is enabled) |

Common optional

| Variable | Default | Description | |---|---|---| | SYNO_PORT | 5001 | DSM port (5000 HTTP, 5001 HTTPS) | | SYNO_HTTPS | true | Use HTTPS | | SYNO_IGNORE_CERT | false | Accept self-signed cert (trusted home NAS only) | | SYNO_OTP_CODE | — | 2FA TOTP code (prefer app-specific passwords instead) | | MCP_TRANSPORT | stdio | stdio or sse | | MCP_SSE_HOST | 127.0.0.1 | Bind address for SSE | | MCP_SSE_PORT | 3100 | Port for SSE | | MCP_AUTH_TOKEN | — | Required when MCP_SSE_HOST is non-loopback | | LOG_LEVEL | info | debug | info | warn | error |

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 37 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": ["/absolute/path/to/synology-office-mcp/dist/index.js"],
      "env": {
        "SYNO_HOST": "192.168.1.100",
        "SYNO_USERNAME": "your_user",
        "SYNO_PASSWORD": "your_password"
      }
    }
  }
}

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

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

| Layer | Tooling | Notes | |---|---|---| | Unit | Vitest | All modules in tests/ — 311 tests | | HTTP mocking | MSW | No real NAS required for unit tests | | Smoke | Vitest, gated by SMOKE_TEST=1 | Hits a real NAS — disabled in CI |

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

| Document | Purpose | |---|---| | tool-reference.md | All 37 tools: name, module, confirm-required, summary | | usage-guide.md | Sample prompts for invoking each tool from an MCP-aware agent | | deployment-guide.md | Docker, systemd unit, Synology scheduled task | | integration-guide.md | Client wiring (Claude, Cursor, Codex, LangChain, …) | | troubleshooting.md | Common Synology error codes + fixes | | security-model.md | Detailed threat model | | CHANGELOG.md | Versioned release notes | | CONTRIBUTING.md | Contributor workflow | | SECURITY.md | Vulnerability disclosure |

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 — <[email protected]>

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.