Skip to main content
Glama
README.md
# synology-chat-mcp

MCP server for [Synology Chat](https://www.synology.com/dsm/feature/chat). Works with any self-hosted Synology Chat instance: list channels, read recent posts, find users, send messages and upload files from any MCP client (Claude Desktop, Claude Code, Hermes, ...).

It logs in as a normal DSM user through the Synology Web API, so it sees exactly what that user sees in Chat (channels and DMs), no bot or webhook setup needed.

## Tools

| Tool | What it does |
|---|---|
| `list_channels()` | Joined channels and DMs (id, name, type, members, unread) |
| `find_user(name_query)` | Find users by partial username |
| `get_recent_posts(channel_id, limit=20)` | Most recent messages/files in a channel or DM |
| `dm_channel_for_user(user_id)` | 1:1 DM channel id for a user, or `null` if none exists yet |
| `send_message(channel_id, message)` | Post a text message |
| `send_file(channel_id, file_path, message="")` | Upload a local file, optionally followed by a message |

## Configuration

All config comes from environment variables, set them in your MCP client config:

| Variable | Required | Example |
|---|---|---|
| `SYNOLOGY_CHAT_URL` | yes | `https://chat.example.com`, `https://nas.local:5001`, `http://192.168.1.10:5000` |
| `SYNOLOGY_CHAT_USER` | yes | DSM username |
| `SYNOLOGY_CHAT_PASS` | yes | DSM password |
| `SYNOLOGY_CHAT_VERIFY_SSL` | no | `false` for self-signed certificates (default `true`) |

A URL without scheme means `https`, without port it uses 443 (https) or 80 (http).

## Install

Needs [uv](https://docs.astral.sh/uv/). No clone required, `uvx` runs it straight from GitHub.

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "synology-chat": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Louis-Lastella/synology-chat-mcp", "synology-chat-mcp"],
      "env": {
        "SYNOLOGY_CHAT_URL": "https://chat.example.com",
        "SYNOLOGY_CHAT_USER": "your-username",
        "SYNOLOGY_CHAT_PASS": "your-password"
      }
    }
  }
}
```

**Claude Code:**

```bash
claude mcp add synology-chat \
  -e SYNOLOGY_CHAT_URL=https://chat.example.com \
  -e SYNOLOGY_CHAT_USER=your-username \
  -e SYNOLOGY_CHAT_PASS=your-password \
  -- uvx --from git+https://github.com/Louis-Lastella/synology-chat-mcp synology-chat-mcp
```

**Hermes** (`~/.hermes/config.yaml`):

```yaml
mcp_servers:
  synology-chat:
    command: uvx
    args: [--from, git+https://github.com/Louis-Lastella/synology-chat-mcp, synology-chat-mcp]
    env:
      SYNOLOGY_CHAT_URL: https://chat.example.com
      SYNOLOGY_CHAT_USER: your-username
      SYNOLOGY_CHAT_PASS: your-password
```

From a local clone instead: `git clone`, `uv sync`, then use `uv` with args `--directory /path/to/synology-chat-mcp run synology-chat-mcp`.

**Docker** (no uv needed), image `ghcr.io/louis-lastella/synology-chat-mcp`:

```json
{
  "mcpServers": {
    "synology-chat": {
      "command": "docker",
      "args": ["run", "-i", "--rm",
               "-e", "SYNOLOGY_CHAT_URL", "-e", "SYNOLOGY_CHAT_USER", "-e", "SYNOLOGY_CHAT_PASS",
               "ghcr.io/louis-lastella/synology-chat-mcp"],
      "env": {
        "SYNOLOGY_CHAT_URL": "https://chat.example.com",
        "SYNOLOGY_CHAT_USER": "your-username",
        "SYNOLOGY_CHAT_PASS": "your-password"
      }
    }
  }
}
```

Also listed in the [official MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.Louis-Lastella/synology-chat-mcp`.

## Notes

- Accounts with 2-factor authentication are not supported (the Web API wants a fresh OTP per login). Use an account without 2FA.
- DMs show up with type `anonymous`, that is Synology's name for 1:1 conversations.
- `find_user` only matches the `username`, not display names.
- Downloading attachments is not a tool yet. The session is available via `synology_chat_mcp._client().session`; call `GET /webapi/entry.cgi?api=SYNO.Chat.Post.File&method=get&version=2&post_id=<id>&_sid=<sid>` with the header `X-SYNO-TOKEN: <session.syno_token>`.

## Development

```bash
uv sync
uv run python tests/test_parse_url.py
```

## License

MIT

TDQS

A3.6/5.0

Scored across 6 tools

Disambiguation5/5

Each tool targets a clearly distinct operation: discovery (list_channels, find_user), reading (get_recent_posts), DM resolution (dm_channel_for_user), and sending (send_message, send_file). There is little risk of confusing send_message with send_file or get_recent_posts with list_channels.

Naming Consistency4/5

Most tools use a predictable snake_case verb_noun pattern: list_channels, find_user, get_recent_posts, send_message, send_file. The one deviation is dm_channel_for_user, which is noun-oriented rather than verb-led, but it remains readable and semantically clear.

Tool Count5/5

Six tools is well-scoped for a chat integration focused on discovery, reading, DM lookup, and sending. Each tool has a distinct and necessary role, with no obvious bloat.

Completeness4/5

The set covers the core chat lifecycle: list channels, find users, resolve DMs, read recent posts, and send messages or files. Minor gaps exist around message search, editing/deleting messages, or channel creation, but core workflows are covered.

Maintenance

ActivitySlowing
ResponsivenessNo recent community issues