Synology MCP Server

Gerencie arquivos e downloads em dispositivos Synology NAS usando um assistente de IA.

GitHub
211
Experimente este MCPPatrocinado

Documentação

💾 Synology MCP Server

Synology MCP Server

Um servidor Model Context Protocol (MCP) para dispositivos Synology NAS. Permite que assistentes de IA gerenciem arquivos e downloads por meio de autenticação segura e gerenciamento de sessão.

🌟 NOVO: Servidor unificado suporta simultaneamente Claude/Cursor (stdio) e Xiaozhi (WebSocket)!

📦 Instalação via PyPI

Não é necessário clonar o repositório — instale o pacote diretamente do PyPI:

# With pip
pip install mcp-server-synology

# Or with pipx (isolated environment)
pipx install mcp-server-synology

# Or with uv
uv tool install mcp-server-synology

Isso instala dois comandos equivalentes: synology-mcp e mcp-server-synology.

Para clientes MCP, uvx é a opção mais simples — ele baixa e armazena em cache o pacote automaticamente, sem instalação manual ou clone local necessário:

{
  "mcpServers": {
    "synology": {
      "command": "uvx",
      "args": ["mcp-server-synology"]
    }
  }
}

A configuração fica fora do pacote, então funciona da mesma forma que um checkout do código-fonte: crie ~/.config/synology-mcp/settings.json conforme descrito em Opções de Configuração.

🚀 Início Rápido com Docker

1️⃣ Configurar o Ambiente

# Clone repository
git clone https://github.com/atom2ueki/mcp-server-synology.git
cd mcp-server-synology

# Create environment file
cp env.example .env

2️⃣ Configurar o Arquivo .env

Configuração Básica (somente Claude/Cursor):

# Required: Synology NAS connection
SYNOLOGY_URL=http://192.168.1.100:5000
SYNOLOGY_USERNAME=your_username
SYNOLOGY_PASSWORD=your_password

# Optional: Auto-login on startup
AUTO_LOGIN=true
VERIFY_SSL=false

Configuração Estendida (Claude/Cursor + Xiaozhi):

# Required: Synology NAS connection
SYNOLOGY_URL=http://192.168.1.100:5000
SYNOLOGY_USERNAME=your_username
SYNOLOGY_PASSWORD=your_password

# Optional: Auto-login on startup
AUTO_LOGIN=true
VERIFY_SSL=false

# Enable Xiaozhi support
ENABLE_XIAOZHI=true
XIAOZHI_TOKEN=your_xiaozhi_token_here
XIAOZHI_MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/

3️⃣ Executar com Docker

Um único comando simples suporta ambos os modos:

# Claude/Cursor only mode (default if ENABLE_XIAOZHI not set)
docker-compose up -d

# Both Claude/Cursor + Xiaozhi mode (if ENABLE_XIAOZHI=true in .env)
docker-compose up -d

# Build and run
docker-compose up -d --build

4️⃣ Alternativa: Python Local

# Install the package and its dependencies (from PyPI, or from a clone with 'pip install .')
pip install mcp-server-synology

# Run with environment control
python main.py

🔌 Configuração do Cliente

Os exemplos abaixo usam Docker com um clone local deste repositório. Se você instalou via PyPI, use a configuração uvx de Instalação via PyPI — ela funciona para Claude Desktop, Cursor, Continue e Codeium, sem necessidade de ajustar caminhos locais.

🤖 Claude Desktop

Adicione ao arquivo de configuração do Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "synology": {
      "command": "docker-compose",
      "args": [
        "-f", "/path/to/your/mcp-server-synology/docker-compose.yml",
        "run", "--rm", "synology-mcp"
      ],
      "cwd": "/path/to/your/mcp-server-synology"
    }
  }
}

↗️ Cursor

Adicione às configurações MCP do Cursor:

{
  "mcpServers": {
    "synology": {
      "command": "docker-compose",
      "args": [
        "-f", "/path/to/your/mcp-server-synology/docker-compose.yml",
        "run", "--rm", "synology-mcp"
      ],
      "cwd": "/path/to/your/mcp-server-synology"
    }
  }
}

🔄 Continue (Extensão do VS Code)

Adicione à configuração do Continue (.continue/config.json):

{
  "mcpServers": {
    "synology": {
      "command": "docker-compose",
      "args": [
        "-f", "/path/to/your/mcp-server-synology/docker-compose.yml",
        "run", "--rm", "synology-mcp"
      ],
      "cwd": "/path/to/your/mcp-server-synology"
    }
  }
}

💻 Codeium

Para o suporte MCP do Codeium:

{
  "mcpServers": {
    "synology": {
      "command": "docker-compose",
      "args": [
        "-f", "/path/to/your/mcp-server-synology/docker-compose.yml",
        "run", "--rm", "synology-mcp"
      ],
      "cwd": "/path/to/your/mcp-server-synology"
    }
  }
}

🐍 Alternativa: Execução Direta em Python

Se preferir não usar Docker:

{
  "mcpServers": {
    "synology": {
      "command": "python",
      "args": ["main.py"],
      "cwd": "/path/to/your/mcp-server-synology",
      "env": {
        "SYNOLOGY_URL": "http://192.168.1.100:5000",
        "SYNOLOGY_USERNAME": "your_username",
        "SYNOLOGY_PASSWORD": "your_password",
        "AUTO_LOGIN": "true",
        "ENABLE_XIAOZHI": "false"
      }
    }
  }
}

🌐 Implantação HTTP Remota Streamable

Por padrão, o servidor fala stdio, o que significa que o cliente MCP precisa iniciar o processo localmente (ou via uma ponte como SSH/docker exec). Para configurações onde o NAS é remoto (em uma máquina diferente de onde Claude/Cursor é executado), defina MCP_HTTP=true e o servidor fornecerá Streamable HTTP nativo a partir do uvicorn no mesmo processo — sem sidecar mcp-proxy e sem endpoint /sse separado. Isso o torna consumível por qualquer cliente MCP que suporte conectores baseados em URL — exatamente como ha-mcp ou outros servidores MCP "remotos".

Arquitetura

[Claude Desktop / Cursor / ...]
        │
        │ HTTPS (URL connector)
        ▼
[Reverse proxy: DSM / Nginx / Traefik / Caddy]
        │  (TLS termination + auth)
        │ HTTP localhost:8765
        ▼
[Docker container]
  └─ python main.py
       └─ uvicorn → Streamable HTTP at /mcp

Implantação

  1. Todas as dependências vêm de pyproject.toml: mcp>=2.0.0 inclui starlette, uvicorn e sse-starlette, então a mesma imagem atende tanto stdio quanto Streamable HTTP — sem argumento de build extra ou arquivo de requisitos separado.
  2. Use o docker-compose.http.yml fornecido:
# Edit credentials in docker-compose.http.yml first
docker compose -f docker-compose.http.yml up -d --build
docker logs -f synology-mcp-http

Você deve ver o log do servidor Starting Streamable HTTP MCP server on http://0.0.0.0:8765/mcp e o login automático bem-sucedido. O banner Uvicorn running on … do próprio uvicorn não é impresso nos padrões do arquivo compose — ele é INFO no logger uvicorn.error, que o servidor fixa em warning a menos que DEBUG=true.

Proxy reverso

A maioria dos clientes MCP exige HTTPS, então o endpoint HTTP deve ser protegido por um proxy reverso com terminação TLS. Para usuários DSM, o Portal de Login → Proxy Reverso integrado resolve:

  • Origem: HTTPS, hostname synology-mcp.example.com, porta 443
  • Destino: HTTP, localhost, porta 8765
  • Cabeçalhos Personalizados: nenhum necessário — Streamable HTTP é POST/GET simples em um único endpoint, não um upgrade WebSocket. O preset Criar → WebSocket é inofensivo se você já o aplica em outro lugar (ele define Connection: upgrade apenas para solicitações de upgrade reais), mas não é o que mantém um stream aberto

Para Nginx, o equivalente é:

location / {
    proxy_pass http://localhost:8765;
    proxy_http_version 1.1;
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    # Responses may stream as long-lived text/event-stream
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 24h;
}

Configuração do cliente

No Claude Desktop (ou qualquer cliente MCP que suporte conectores remotos), adicione um conector personalizado apontando para:

https://synology-mcp.example.com/mcp

O caminho é o que MCP_HTTP_PATH estiver definido (padrão /mcp). Sem command, sem args, sem Python local — apenas uma URL.

Segurança

O servidor não implementa autenticação em nível de aplicação — qualquer coisa que possa alcançar o endpoint HTTP pode chamar todas as ferramentas. Ele habilita a proteção contra rebinding de DNS do SDK MCP, que rejeita solicitações cujos cabeçalhos Host/Origin não estejam em uma lista de permissões (MCP_HTTP_ALLOWED_HOSTS / MCP_HTTP_ALLOWED_ORIGINS, com padrão loopback). Atrás de um proxy reverso, defina ambos, observando os formatos diferentes — hosts são simples (synology-mcp.example.com), origins são qualificadas por esquema (https://synology-mcp.example.com), como nos exemplos comentados em docker-compose.http.yml. Isso protege navegadores contra ataques de rebinding; não é autenticação. Mitigações:

  • Mantenha-o em uma rede privada ou atrás de uma VPN
  • Deixe a porta publicada em loopback (docker-compose.http.yml vincula 127.0.0.1:8765) para que apenas um proxy reverso no mesmo host possa alcançá-la
  • Use o proxy reverso para impor uma lista de permissões de IP
  • Adicione Basic Auth / mTLS / proxy OAuth2 na camada do proxy reverso
  • Use um usuário DSM dedicado com privilégios baixos (já recomendado no aviso de segurança acima)

🌟 Integração Xiaozhi

Nova arquitetura unificada suporta ambos os clientes simultaneamente!

Como Funciona

  • ENABLE_XIAOZHI=false (padrão): Servidor MCP padrão para Claude/Cursor via stdio
  • ENABLE_XIAOZHI=true: Ponte multi-cliente suportando ambos:
    • 📡 Xiaozhi: Conexão WebSocket
    • 💻 Claude/Cursor: Conexão stdio

Etapas de Configuração

  1. Adicione ao seu arquivo .env:
ENABLE_XIAOZHI=true
XIAOZHI_TOKEN=your_xiaozhi_token_here
  1. Execute normalmente:
# Same command, different behavior based on environment
python main.py
# OR
docker-compose up

Principais Recursos

  • ✅ Zero Conflitos de Configuração: Um servidor, múltiplos clientes
  • ✅ Operação Paralela: Ambos os clientes podem trabalhar simultaneamente
  • ✅ Todas as Ferramentas Disponíveis: Xiaozhi obtém acesso a todas as ferramentas MCP do Synology
  • ✅ Compatível com Versões Anteriores: Configurações existentes funcionam sem alterações
  • ✅ Reconexão Automática: Gerencia quedas de conexão WebSocket
  • ✅ Controlado por Ambiente: Flag booleana simples para habilitar/desabilitar

Mensagens de Inicialização

Modo somente Claude/Cursor:

🚀 Synology MCP Server
==============================
📌 Claude/Cursor only mode (ENABLE_XIAOZHI=false)

Modo ambos os clientes:

🚀 Synology MCP Server with Xiaozhi Bridge
==================================================
🌟 Supports BOTH Xiaozhi and Claude/Cursor simultaneously!

🛠️ Ferramentas MCP Disponíveis

🔐 Autenticação

  • synology_status - Verifica o status de autenticação e sessões ativas
  • synology_list_nas - Lista todas as unidades NAS configuradas em settings.json
  • synology_login - Autentica com o Synology NAS (condicional)
  • synology_logout - Encerra a sessão (condicional)

📁 Operações do Sistema de Arquivos

  • list_shares - Lista todos os compartilhamentos NAS disponíveis
  • list_directory - Lista o conteúdo do diretório com metadados
    • path (obrigatório): Caminho do diretório começando com /
  • get_file_info - Obtém informações detalhadas de arquivo/diretório
    • path (obrigatório): Caminho do arquivo começando com /
  • get_file_content - Lê texto UTF-8 estrito ou conteúdo base64 sem perdas
    • path (obrigatório): Caminho do arquivo começando com /
    • encoding (opcional): text (padrão) ou base64
    • max_bytes (opcional): Máximo de bytes brutos a ler (padrão 1 MiB, limite máximo 8 MiB)
  • search_files - Busca recursivamente arquivos e pastas por nome
    • path (obrigatório): Diretório de busca
    • pattern (obrigatório): Substring do nome sem diferenciar maiúsculas/minúsculas (ex.: invoice, .pdf). Caracteres curinga não são especiais — DSM trata report e *report* de forma idêntica.
  • create_file - Cria novos arquivos com conteúdo
    • path (obrigatório): Caminho completo do arquivo começando com /
    • content (opcional): Conteúdo do arquivo (padrão: string vazia)
    • overwrite (opcional): Sobrescrever arquivos existentes (padrão: false)
    • encoding (opcional): text (padrão) ou base64 estrito; o conteúdo decodificado é limitado a 8 MiB
  • create_directory - Cria novos diretórios
    • folder_path (obrigatório): Caminho do diretório pai começando com /
    • name (obrigatório): Nome do novo diretório
    • force_parent (opcional): Criar diretórios pai se necessário (padrão: false)
  • delete - Exclui arquivos ou diretórios (detecta o tipo automaticamente)
    • path (obrigatório): Caminho do arquivo/diretório começando com /
  • rename_file - Renomeia arquivos ou diretórios
    • path (obrigatório): Caminho atual do arquivo
    • new_name (obrigatório): Novo nome do arquivo
  • move_file - Move arquivos para um novo local
    • source_path (obrigatório): Caminho do arquivo de origem
    • destination_path (obrigatório): Caminho de destino
    • overwrite (opcional): Sobrescrever arquivos existentes
  • copy_file - Copia um arquivo regular dentro do NAS sem enviar seus bytes pelo cliente MCP
    • source_path (obrigatório): Caminho do arquivo de origem
    • destination_folder (obrigatório): Diretório de destino existente; o nome do arquivo é preservado
    • overwrite (opcional): Sobrescrever um arquivo existente com o mesmo nome (padrão: false)

copy_file verifica o caminho de destino e a contagem de bytes. Não é um método de backup consistente para um banco de dados SQLite ativo; use o mecanismo de backup online do SQLite para bancos de dados que possam estar mudando durante a cópia.

📥 Gerenciamento da Download Station

  • ds_get_info - Obtém informações da Download Station
  • ds_list_tasks - Lista todas as tarefas de download com status
    • offset (opcional): Deslocamento de paginação
    • limit (opcional): Máximo de tarefas a retornar
  • ds_create_task - Cria nova tarefa de download
    • uri (obrigatório): URL de download ou link magnet
    • destination (opcional): Caminho da pasta de download
  • ds_pause_tasks - Pausa tarefas de download
    • task_ids (obrigatório): Matriz de IDs de tarefas
  • ds_resume_tasks - Retoma tarefas pausadas
    • task_ids (obrigatório): Matriz de IDs de tarefas
  • ds_delete_tasks - Exclui tarefas de download
    • task_ids (obrigatório): Matriz de IDs de tarefas
    • force_complete (opcional): Forçar exclusão de concluídas
  • ds_get_statistics - Obtém estatísticas de download/upload

🏥 Monitoramento de Saúde

  • synology_system_info - Obtém modelo do sistema, número de série, versão DSM, tempo de atividade, temperatura
  • synology_utilization - Obtém utilização em tempo real de CPU, memória, swap e I/O de disco
  • synology_disk_health - Lista todos os discos físicos com status SMART, modelo, temperatura, tamanho
  • synology_disk_smart - Obtém atributos SMART detalhados para um disco específico
  • synology_volume_status - Lista todos os volumes com status, tamanho, uso, tipo de sistema de arquivos
  • synology_storage_pool - Lista pools RAID/armazenamento com nível, status, discos membros
  • synology_lun_list - Lista todos os LUNs iSCSI com nome, UUID, tamanho, tipo, status e volume de suporte. Para ver a qual target um LUN está conectado, use synology_target_list - o DSM não reporta mapeamentos no lado do LUN.
  • synology_lun_get - Obtém detalhes de um único LUN iSCSI
    • name (obrigatório): Nome do LUN ou UUID da saída de synology_lun_list
  • synology_network - Obtém status da interface de rede e taxas de transferência

Gerenciador SAN (provisionamento iSCSI)

Encapsula SYNO.Core.ISCSI.LUN e SYNO.Core.ISCSI.Target. Verificado no DSM 7.3.2-86009 Update 4 em um RS1221+; outras versões do DSM podem diferir, e a própria recusa do DSM é reportada como fornecida, sem ser questionada.

  • synology_lun_create - Cria um LUN em um volume; retorna seu uuid e lun_id
    • name, location (ex.: /volume2), size (em bytes) obrigatórios
    • type (opcional): thin (padrão, DSM BLUN), advanced, file ou um nome de tipo DSM bruto. Observe que thin e THIN são diferentes: minúsculas é o alias amigável para BLUN, maiúsculas é o tipo legado distinto do DSM. Tipos thick foram recusados no volume btrfs em que isso foi testado.
    • description (opcional)
  • synology_lun_delete - DESTRUTIVO. Exclui um LUN e tudo o que está nele
    • uuid e confirm: true obrigatórios
  • synology_target_list - Lista targets com IQN, tipo de autenticação e os LUNs mapeados para cada um
  • synology_target_get - Obtém um target por target_id
  • synology_target_create - Cria um target; retorna seu target_id
    • name obrigatório; iqn assume o padrão iqn.2000-01.com.synology:<name>
    • chap_user + chap_password habilitam CHAP. Forneça ambos ou nenhum - apenas um, ou uma string vazia, é recusado em vez de produzir silenciosamente um target sem autenticação. Com nenhum, o target aceita qualquer iniciador que consiga alcançá-lo.
    • max_sessions (opcional, 0 = padrão do DSM)
  • synology_target_map_lun - Mapeia LUNs para um target (target_id, lun_uuids)
  • synology_target_unmap_lun - DESTRUTIVO. Desmapeia LUNs, desconectando qualquer iniciador que os esteja usando (target_id, lun_uuids, confirm: true)

Essas ferramentas rejeitam qualquer argumento que não declaram, em vez de ignorá-lo: um chap_user com erro de digitação criaria, de outra forma, um target não autenticado, e um type com erro de digitação assumiria silenciosamente o padrão.

  • synology_ups - Obtém status do UPS, nível da bateria, leituras de energia
  • synology_services - Lista pacotes instalados e seu status de execução
  • synology_system_log - Obtém entradas recentes do log do sistema
  • synology_health_summary - Agrega informações do sistema, utilização, saúde do disco e status do volume

🐳 Container Manager

  • synology_container_list - Lista contêineres do Container Manager
    • offset (opcional): Deslocamento de paginação
    • limit (opcional): Máximo de contêineres a retornar
    • container_type (opcional): Filtro de contêiner (padrão: all)
  • synology_container_health_summary - Resume o status do contêiner, saúde, contagens de reinicialização e imagens
  • synology_container_disk_usage - Mostra o resumo de uso de disco somente leitura disponível pelas APIs do Container Manager
  • synology_container_get - Obtém um contêiner do Container Manager
    • name (obrigatório): Nome do contêiner
  • synology_container_start - Inicia um contêiner do Container Manager
    • name (obrigatório): Nome do contêiner
  • synology_container_stop - Para um contêiner do Container Manager
    • name (obrigatório): Nome do contêiner
  • synology_container_restart - Reinicia um contêiner do Container Manager
    • name (obrigatório): Nome do contêiner
  • synology_container_delete - Exclui um contêiner do Container Manager
    • name (obrigatório): Nome do contêiner
    • force (opcional): Forçar exclusão (padrão: false)
    • preserve_profile (opcional): Preservar perfil de contêiner Synology (padrão: true)
  • synology_container_logs - Obtém logs de contêiner do Container Manager
    • name (obrigatório): Nome do contêiner
    • since (opcional): Tempo de início/filtro do log
    • offset (opcional): Deslocamento de paginação (padrão: 0)
    • limit (opcional): Máximo de linhas de log a retornar (padrão: 1000)
  • synology_container_resource - Obtém uso de recursos em tempo real para um contêiner do Container Manager
    • name (obrigatório): Nome do contêiner
  • synology_container_project_list - Lista projetos do Container Manager
  • synology_container_project_get - Obtém um projeto do Container Manager (campos Compose, ambiente e segredo são omitidos)
    • name (obrigatório): Nome do projeto
  • synology_container_project_create - Cria e salva uma definição de projeto do Container Manager
    • name (obrigatório): Nome do projeto
    • share_path (obrigatório): Caminho da pasta do projeto no NAS
    • content (obrigatório): Conteúdo YAML do Docker Compose
    • enable_service_portal (opcional): Habilitar portal de serviço Synology (padrão: false)
    • service_portal_name (opcional): Nome do portal de serviço
    • service_portal_port (opcional): Porta do portal de serviço
    • service_portal_protocol (opcional): Protocolo do portal de serviço (padrão: http)
    • Salva a definição do Compose; chame synology_container_project_build para materializá-la.
  • synology_container_project_update - Atualiza um projeto do Container Manager
    • name (obrigatório): Nome do projeto
    • content (obrigatório): Conteúdo YAML do Docker Compose
    • enable_service_portal (opcional): Habilitar portal de serviço Synology
    • service_portal_name (opcional): Nome do portal de serviço
    • service_portal_port (opcional): Porta do portal de serviço
    • service_portal_protocol (opcional): Protocolo do portal de serviço
  • synology_container_project_start - Inicia um projeto do Container Manager
    • name (obrigatório): Nome do projeto
  • synology_container_project_stop - Para um projeto do Container Manager
    • name (obrigatório): Nome do projeto
  • synology_container_project_restart - Reinicia um projeto do Container Manager
    • name (obrigatório): Nome do projeto
  • synology_container_project_build - Materializa ou reconstrói um projeto salvo do Container Manager
    • name (obrigatório): Nome do projeto
  • synology_container_project_clean - Limpa um projeto do Container Manager
    • name (obrigatório): Nome do projeto
  • synology_container_project_delete - Exclui um projeto do Container Manager
    • name (obrigatório): Nome do projeto
  • synology_container_image_list - Lista imagens do Container Manager
    • offset (opcional): Deslocamento de paginação
    • limit (opcional): Máximo de imagens a retornar
    • show_dsm (opcional): Incluir imagens do DSM (padrão: false)
  • synology_container_image_get - Obtém uma imagem do Container Manager
    • name (obrigatório): Nome do repositório da imagem
    • tag (opcional): Tag da imagem (padrão: latest)
  • synology_container_image_delete - Exclui uma imagem do Container Manager
    • name (obrigatório): Nome do repositório da imagem
    • tag (opcional): Tag da imagem (padrão: latest)
  • synology_container_image_prune - Remove imagens não usadas por nenhum contêiner
    • synology_container_image_prune_preview fornece uma lista de candidatos somente leitura antes da limpeza
    • Usa apenas APIs do Container Manager para excluir com segurança imagens marcadas não usadas identificáveis e relata imagens pendentes que não pode remover pelo DSM
    • Não remove contêineres, redes ou cache de build
  • synology_container_image_pull - Baixa uma imagem do Container Manager
    • repository (obrigatório): Nome do repositório da imagem
    • tag (opcional): Tag da imagem (padrão: latest)
  • synology_container_registry_list - Lista registries do Container Manager
  • synology_container_registry_search - Pesquisa registries do Container Manager
    • query (obrigatório): Consulta de pesquisa de imagem
    • offset (opcional): Deslocamento de paginação
    • limit (opcional): Máximo de resultados a retornar
  • synology_container_registry_tags - Lista tags para uma imagem de registry
    • repository (obrigatório): Nome do repositório da imagem
    • offset (opcional): Deslocamento de paginação
    • limit (opcional): Máximo de tags a retornar
  • synology_container_registry_download - Baixa uma imagem de registry
    • repository (obrigatório): Nome do repositório da imagem
    • tag (opcional): Tag da imagem (padrão: latest)
  • synology_container_network_list - Lista redes do Container Manager
  • synology_container_network_get - Obtém uma rede do Container Manager
    • name (obrigatório): Nome da rede
  • synology_container_network_create - Cria uma rede do Container Manager
    • name (obrigatório): Nome da rede
    • driver (opcional): Driver de rede (padrão: bridge)
    • subnet (opcional): CIDR da sub-rede
    • gateway (opcional): IP do gateway
    • ip_range (opcional): Faixa de IP alocável em CIDR
    • enable_ipv6 (opcional): Habilitar IPv6 (padrão: false)
  • synology_container_network_delete - Exclui uma rede do Container Manager
    • name (obrigatório): Nome da rede

📦 Gerenciamento de NFS

  • synology_nfs_status - Obtém status e configuração do serviço NFS
  • synology_nfs_enable - Habilita ou desabilita o serviço NFS
  • synology_nfs_list_shares - Lista todas as pastas compartilhadas com suas permissões NFS
  • synology_nfs_set_permission - Define permissões de acesso de cliente NFS em uma pasta compartilhada

🧠 Habilidade para Claude Code / Claude.ai

Para usuários de Claude Code, Claude Desktop e claude.ai, este repositório inclui uma Habilidade de Agente Anthropic que ensina o Claude a usar as ferramentas MCP de forma eficaz — escolhendo a ferramenta certa, direcionando o NAS correto em configurações com vários NAS, preferindo verificações de saúde agregadas em vez de chamadas dispersas e usando convenções de caminho corretas.

A habilidade está em skills/synology-nas/ e usa divulgação progressiva em sete domínios (auth, arquivos, downloads, saúde, contêineres, compartilhamentos/NFS, gerenciamento de usuários).

Instalação:

  • Claude Code: copie ou crie um symlink da pasta para ~/.claude/skills/synology-nas/
  • Claude.ai / Claude Desktop: envie a pasta synology-nas/ pela página de configurações de Skills

A habilidade é puramente aditiva — funciona junto com o MCP e só é acionada em prompts relacionados a Synology/NAS.

⚙️ Opções de Configuração

⚠️ Aviso de Segurança: Use uma Conta Dedicada

Para este servidor MCP, crie uma conta de usuário Synology dedicada com permissões apropriadas. Esta conta deve:

  • Ter apenas as permissões mínimas necessárias (não admin!)
  • Ser usada exclusivamente para automação do servidor MCP
  • 2FA agora é suportado — se sua conta DSM tiver 2FA habilitado, consulte a seção Contas 2FA / OTP abaixo para fornecer um campo otp_code (uso único) ou device_id (persistente). A orientação antiga de "sem 2FA" não é mais necessária.

Usando settings.json (Recomendado)

VariávelObrigatóriaPadrãoDescrição
SYNOLOGY_URLSim*-URL base do NAS (ex.: http://192.168.1.100:5000)
SYNOLOGY_USERNAMESim*-Nome de usuário para autenticação
SYNOLOGY_PASSWORDSim*-Senha para autenticação
AUTO_LOGINNãotrueLogin automático na inicialização do servidor
VERIFY_SSLNãofalseVerificar certificados SSL
DEBUGNãofalseHabilitar log de depuração
ENABLE_XIAOZHINãofalseHabilitar ponte WebSocket Xiaozhi
XIAOZHI_TOKENSomente Xiaozhi-Token de autenticação para Xiaozhi
XIAOZHI_MCP_ENDPOINTNãowss://api.xiaozhi.me/mcp/Endpoint WebSocket Xiaozhi

*Obrigatórias para login automático e operações padrão

Usando settings.json (Suporte Multi-NAS)

Para gerenciar vários dispositivos Synology NAS, use o diretório de configuração padrão XDG (~/.config/synology-mcp/settings.json):

mkdir -p ~/.config/synology-mcp
touch ~/.config/synology-mcp/settings.json
chmod 600 ~/.config/synology-mcp/settings.json  # Important: secure permissions!

Observação: Isso segue a Especificação de Diretório Base XDG - ~/.config/ é o local padrão para arquivos de configuração do usuário em Linux/macOS. Você pode personalizar o local definindo a variável de ambiente XDG_CONFIG_HOME.

Com Docker: O docker-compose.yml monta automaticamente seu diretório ~/.config/synology-mcp no contêiner em /home/mcpuser/.config/synology-mcp, então multi-NAS funciona prontamente com Docker também.

Formato do settings.json:

{
  "synology": {
    "nas1": {
      "host": "192.168.1.100",
      "port": 5000,
      "username": "admin",
      "password": "your_password",
      "note": "Primary NAS at home"
    },
    "nas2": {
      "host": "192.168.1.200",
      "port": 5001,
      "username": "admin",
      "password": "your_password",
      "note": "Backup NAS"
    },
    "nas3": {
      "url": "https://nas.example.com",
      "username": "admin",
      "password": "your_password",
      "note": "NAS behind a reverse proxy"
    }
  },
  "xiaozhi": {
    "enabled": false,
    "token": "your_xiaozhi_token",
    "endpoint": "wss://api.xiaozhi.me/mcp/"
  },
  "server": {
    "auto_login": true,
    "verify_ssl": false,
    "session_timeout": 3600,
    "debug": false,
    "log_level": "INFO"
  }
}

Campos de configuração:

CampoObrigatórioDescrição
hostSim*Hostname ou endereço IP do NAS
portNãoPorta da API (padrão: 5000 para HTTP, 5001 para HTTPS)
urlSim*URL base completa (ex.: https://nas.example.com); tem prioridade sobre host/port — use para um NAS atrás de um proxy reverso
usernameSimNome de usuário do NAS
passwordSimSenha do NAS
otp_codeNãoCódigo 2FA de 6 dígitos de uso único (somente no primeiro login, depois remova)
device_idNãoToken de dispositivo confiável de longa duração do DSM (did); pula OTP em todos os logins futuros
noteNãoDescrição opcional para sua referência

*Ou host ou url é obrigatório por entrada de NAS.

Observações:

  • O servidor usará a porta 5001 (HTTPS) se a porta for 5001, caso contrário, o padrão é HTTP (5000)
  • O formato host/port sempre acrescenta uma porta e deriva o esquema dela, portanto não consegue expressar https://nas.example.com na porta padrão 443 — defina url diretamente para configurações com proxy reverso
  • Permissões de arquivo: chmod 600 ~/.config/synology-mcp/settings.json é obrigatório por segurança
  • O servidor se recusará a carregar as configurações se as permissões forem muito abertas
  • Tanto .env quanto settings.json podem ser usados juntos (settings.json tem prioridade)

⚠️ Recomendações de Segurança

Permissões do arquivo settings.json:

  • Linux/macOS (POSIX): chmod 600 ~/.config/synology-mcp/settings.json é obrigatório. O servidor se recusa a carregar o arquivo se ele for legível/gravável por grupo ou por outros usuários, ou se pertencer a outro usuário.
  • Windows: O controle de acesso é aplicado via ACLs NTFS, não por bits de modo POSIX. O servidor audita o descritor de segurança do arquivo e se recusa a carregar a menos que todas as três condições sejam atendidas: (1) o SID do proprietário corresponde ao usuário atual; (2) o DACL está presente (um DACL NULL — "acesso total para todos" — é rejeitado); (3) nenhum ACE de permissão concede acesso a um principal fora da lista de permissões: o usuário atual, NT AUTHORITY\SYSTEM e BUILTIN\Administrators. Qualquer concessão herdada de Everyone / BUILTIN\Users / Authenticated Users falha na verificação.

    • Requer o pacote opcional pywin32: pip install pywin32. Se o pywin32 não estiver instalado, o servidor falha de forma segura e se recusa a carregar settings.json. Operadores que aceitam o risco de um arquivo não verificado podem optar novamente definindo SYNOLOGY_MCP_ALLOW_UNVERIFIED_WINDOWS_ACL=true.

    • O servidor resolve o arquivo via XDG_CONFIG_HOME (padrão Path.home() / ".config"), então no Windows ele fica em %USERPROFILE%\.config\synology-mcp\settings.json a menos que XDG_CONFIG_HOME esteja definido.

    • Bloqueie o arquivo a partir de um prompt elevado do PowerShell (usa o mesmo caminho que o servidor carrega):

      # Resolve the path the SAME way the server does: $XDG_CONFIG_HOME if set,
# otherwise %USERPROFILE%\.config. This honors the override documented above.
$cfg = if ($env:XDG_CONFIG_HOME) { $env:XDG_CONFIG_HOME } else { "$env:USERPROFILE\.config" }
$f = "$cfg\synology-mcp\settings.json"

# The server's ACL audit requires: owner == current user, no NULL DACL, and
# no allow-ACE outside {current user, SYSTEM, Administrators}. The steps
# below enforce all three.
#
# Use the *<SID> form for every built-in principal: account names like
# "Administrators" / "Everyone" / "Users" are localized on non-English
# Windows (e.g. German "Administratoren") and won't resolve. The
# locale-independent SIDs:
#   *S-1-1-0            Everyone
#   *S-1-5-11           Authenticated Users
#   *S-1-5-32-545       BUILTIN\Users
#   *S-1-5-32-544       BUILTIN\Administrators
#
# 1. Ensure the file is owned by the current user (the audit rejects any
#    other owner). /setowner requires elevation.
icacls $f /setowner "${env:USERNAME}"
# 2. Drop inherited ACEs, then revoke the common foreign grants. /grant:r
#    only replaces the named principal, so revoke first.
icacls $f /inheritance:r
icacls $f /remove:g "*S-1-1-0" "*S-1-5-11" "*S-1-5-32-545"
# Re-run `icacls $f` here; if any principal other than your user or
# Administrators still appears, run: icacls $f /remove:g "<that principal>"
# 3. Grant the current user and Administrators full control.
icacls $f /grant:r "${env:USERNAME}:(F)"
icacls $f /grant:r "*S-1-5-32-544:(F)"   # BUILTIN\Administrators (locale-independent)

      Se o arquivo for novo, a etapa /remove:g é um no-op inofensivo.

    • Verifique: icacls "$f" — apenas seu usuário e *S-1-5-32-544 (Administradores) devem aparecer.

Verificação de Certificado SSL (VERIFY_SSL):

  • O padrão é false para suportar certificados autoassinados em dispositivos NAS internos
  • Se o seu NAS tiver um certificado SSL válido (ex.: do Let's Encrypt ou de uma CA corporativa), defina VERIFY_SSL=true
  • Definir VERIFY_SSL=false desativa a verificação de certificado e torna sua conexão vulnerável a ataques man-in-the-middle (MITM)
  • Nunca desative a verificação SSL em redes não confiáveis

Auto-Login (AUTO_LOGIN):

  • O padrão é true para conveniência com settings.json
  • As credenciais são armazenadas com segurança em ~/.config/synology-mcp/settings.json com permissões 0600
  • Se você preferir login manual, defina AUTO_LOGIN=false e use a ferramenta synology_login

Contas 2FA / OTP (opcional):

O servidor MCP suporta contas DSM com 2FA habilitado. Há duas maneiras de usar:

  1. OTP de uso único via ferramenta synology_login (interativo):

    { "base_url": "https://nas.lan:5001", "username": "alice", "password": "…", "otp_code": "123456" }

    O DSM retornará um did (token de dispositivo) na resposta — copie esse valor para settings.json (abaixo) para pular o OTP em reinicializações futuras do processo.

  2. Token de dispositivo confiável persistente (recomendado para AUTO_LOGIN=true):

    Adicione os campos otp_code (uso único, somente no primeiro login) e/ou device_id (longa duração, contínuo) por NAS em settings.json:

    {
  "synology": {
    "nas1": {
      "host": "192.168.1.100", "port": 5001,
      "username": "alice", "password": "…",
      "otp_code": "123456",
      "note": "primary — 2FA enabled"
    }
  }
}

    Fluxo de trabalho:

    1. Defina otp_code com um código novo de 6 dígitos do seu autenticador e inicie o servidor.
    2. No primeiro login bem-sucedido, o servidor registra uma linha de aviso como: nas1: 2FA bootstrap — copy this device_id into settings.json to skip OTP on future starts: <did> Copie o valor de <did>.
    3. Cole-o em device_id e exclua otp_code.
    4. A partir de agora, o DSM trata este processo como um dispositivo confiável — reinicializações, novos logins após o erro 119 do DSM e sessões do gerenciador de contêineres pulam o OTP.

    Quando device_id está presente, ele tem precedência sobre otp_code (caminho do dispositivo confiável). Usuários legados de .env podem definir a variável de ambiente de uso único SYNOLOGY_OTP_CODE; para device_id persistente, migre para settings.json (token opaco longo não cabe bem em uma variável de ambiente).

📖 Exemplos de Uso

📁 Operações de Arquivo

✅ Criando Arquivos e Diretórios

File Creation

// List directory
{
  "path": "/volume1/homes"
}

// Search for PDFs
{
  "path": "/volume1/documents", 
  "pattern": ".pdf"
}

// Create new file
{
  "path": "/volume1/documents/notes.txt",
  "content": "My important notes\nLine 2 of notes",
  "overwrite": false
}

🗑️ Excluindo Arquivos e Diretórios

File Deletion

// Delete file or directory (auto-detects type)
{
  "path": "/volume1/temp/old-file.txt"
}

// Move file
{
  "source_path": "/volume1/temp/file.txt",
  "destination_path": "/volume1/archive/file.txt"
}

⬇️ Gerenciamento de Downloads

🛠️ Criando uma Tarefa de Download

Download Sample

// Create download task
{
  "uri": "https://example.com/file.zip",
  "destination": "/volume1/downloads"
}

// Pause tasks
{
  "task_ids": ["dbid_123", "dbid_456"]
}

🦦 Resultados de Download

Download Result

✨ Recursos

  • ✅ Ponto de Entrada Unificado - Um único main.py suporta clientes stdio e WebSocket
  • ✅ Controlado por Ambiente - Alterne modos via variável de ambiente ENABLE_XIAOZHI
  • ✅ Suporte a Múltiplos Clientes - Acesso simultâneo Claude/Cursor + Xiaozhi
  • ✅ Autenticação Segura - Transmissão de senha criptografada com RSA
  • ✅ Gerenciamento de Sessões - Sessões persistentes em vários dispositivos NAS
  • ✅ Operações Completas de Arquivo - Criar, excluir, listar, pesquisar, renomear, mover arquivos com metadados detalhados
  • ✅ Gerenciamento de Diretórios - Operações recursivas de diretório com verificações de segurança
  • ✅ Download Station - Gerenciamento completo de torrents e downloads
  • ✅ Suporte a Docker - Implantação fácil em contêineres
  • ✅ Compatibilidade Retroativa - Configurações existentes funcionam sem alterações
  • ✅ Tratamento de Erros - Relatórios de erro abrangentes e recuperação

🏗️ Arquitetura

Estrutura de Arquivos

mcp-server-synology/
├── main.py                    # 🎯 Unified entry point
├── src/
│   ├── mcp_server.py         # Standard MCP server
│   ├── multiclient_bridge.py # Multi-client bridge
│   ├── auth/                 # Authentication modules
│   ├── filestation/          # File operations
│   └── downloadstation/      # Download management
├── docker-compose.yml        # Single service, environment-controlled
├── Dockerfile
├── pyproject.toml            # Dependencies (single source of truth)
└── .env                      # Configuration

Seleção de Modo

  • ENABLE_XIAOZHI=false → main.py → mcp_server.py (somente stdio)
  • ENABLE_XIAOZHI=true → main.py → multiclient_bridge.py → mcp_server.py (ambos os clientes)

Perfeito para qualquer fluxo de trabalho — desde uso simples com Claude/Cursor até configurações avançadas com múltiplos clientes! 🚀