Nautilus MCP Server

O que é

É um servidor Model Context Protocol (MCP) que fala com o assistente pela entrada/saída padrão (stdio). Está publicado no npm como nautilus-mcp-server e precisa de Node.js 18 ou superior. Recomenda-se executar com npx -y nautilus-mcp-server@latest para o npx resolver sempre o dist-tag latest (evita reutilizar cache de instalação antiga). Se precisar travar em uma versão exata, use nautilus-mcp-server@<versão> no lugar de @latest.

O que faz

• Bancos SQL (PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, Oracle): listar tabelas, ver colunas e índices, executar apenas consultas de leitura (SELECT / WITH) com validação de segurança e limite de linhas, e pequenas amostras de dados.
• MongoDB: listar coleções, buscar documentos com filtro em JSON e paginação, ver índices da coleção, amostra rápida.
• Redis: listar chaves (com padrão e cursor), ler valores conforme o tipo da chave (string, hash, lista, set, sorted set, stream e RedisJSON), com decode seguro de binário e teto de bytes por valor; amostra rápida.

Em muitas respostas o cliente recebe também structuredContent (JSON estruturado) além do texto, para quem consome colunas, linhas, documentos ou chaves sem depender só de texto formatado.

Comportamento padrão: somente leitura no SQL; tamanho de query, timeout e número de linhas/registros têm defaults globais no YAML (bloco defaults) e podem ser sobrescritos por conexão (veja abaixo).

Tools

Resources (MCP)

Como configurar as conexões

As conexões ficam num único arquivo YAML. O servidor lê o caminho de NAUTILUS_CONFIG (padrão ./nautilus.yaml) e valida na subida, falhando cedo com mensagem clara se algo estiver inconsistente. Veja nautilus.yaml.example para um modelo completo.

Cada conexão tem um identificador (connection_id): letras, números e underscores (ex.: pg_prod, mongo_app).

A senha fica cifrada no YAML. O campo password só é aceito cifrado (formato enc:...); texto puro é recusado na subida. Para gravar uma senha, use o CLI nautilus (abaixo), que a cifra com a chave NAUTILUS_KEY antes de escrever no arquivo. Não há interpolação de ${VAR}: todos os demais campos (host, user, database, url) vão literais no YAML. Os únicos valores lidos do ambiente são NAUTILUS_CONFIG e NAUTILUS_KEY.

Cadastrar conexões pelo CLI

Toda adição, alteração e remoção de conexão passa pelo CLI — ele edita o nautilus.yaml e cifra a senha na hora. A chave de criptografia vive fora do YAML, na variável NAUTILUS_KEY (sem ela, o valor cifrado é inútil).

# 1. Gere a chave uma vez e exporte-a no ambiente (guarde-a com segurança)
nautilus keygen                       # imprime a chave; defina NAUTILUS_KEY com ela

# 2. Gerencie as conexões (a senha é pedida de forma oculta e cifrada ao salvar)
nautilus add pg_prod                  # pergunta type/host/port/user/senha/database
nautilus list                         # lista as conexões (nunca mostra a senha)
nautilus edit pg_prod                 # altera campos; senha em branco mantém a atual
nautilus remove pg_prod               # remove a conexão

# Use --config para apontar outro arquivo (padrão: NAUTILUS_CONFIG ou ./nautilus.yaml)
nautilus --config C:/caminho/nautilus.yaml list

Importante: a mesma NAUTILUS_KEY usada no nautilus add precisa estar no ambiente do servidor — é com ela que o Nautilus decifra as senhas ao subir. Troca de chave implica regravar as senhas.

Estrutura

defaults:                 # valores herdados por todas as conexões (todos opcionais)
  read_only: true
  query_timeout_ms: 30000
  connect_timeout_ms: 5000
  max_rows: 200
  default_rows: 50
  query_max_length: 2000

connections:
  <connection_id>:
    type: <engine>        # obrigatório
    # ...atributos da conexão...

Por conexão

• type (obrigatório): um entre postgresql, mysql, mariadb (tratado como MySQL), sqlite, sqlserver, oracle, mongodb, redis.
• Conexão, em um dos dois formatos:
  • url: URL completa (ex.: postgresql://user:senha@host:5432/banco). Para SQLite use url: ":memory:" ou url: "file:...", ou o atalho path:.
  • Ou campos separados (útil se a senha tem @, :, /): host, port, user, password, database (ou db). A porta pode ir junto em host (db.exemplo.com:3306); omitida, usa-se a padrão por tipo (PostgreSQL 5432, MySQL 3306, SQL Server 1433, Oracle 1521, MongoDB 27017, Redis 6379).
• Overrides opcionais do defaults: read_only, query_timeout_ms, connect_timeout_ms. Redis aceita ainda socket_timeout_ms (teto por operação; padrão = query_timeout_ms).

Exemplos

PostgreSQL por URL, com timeout maior só nesta conexão:

connections:
  pg:
    type: postgresql
    url: "postgresql://leitor:senha@db.interno:5432/vendas"
    query_timeout_ms: 60000

PostgreSQL por componentes, não somente-leitura (a senha cifrada foi gravada por nautilus add/edit):

connections:
  pg_app:
    type: postgresql
    host: localhost
    port: 5432
    user: myuser
    password: "enc:gAAAAAB..."   # gerado pelo CLI; nunca edite à mão
    database: mydb
    read_only: false

Redis com teto de operação:

connections:
  cache:
    type: redis
    url: "redis://cache.interno:6379/0"
    socket_timeout_ms: 10000

Como usar nos clientes

Em qualquer cliente MCP com transporte stdio, configure:

• Comando: npx (no Windows, se necessário, use o caminho completo de npx.cmd).
• Argumentos: use ["-y", "nautilus-mcp-server@latest"]. Opcionalmente fixe versão com ["-y", "nautilus-mcp-server@<versão>"].
• Variáveis de ambiente (as únicas): NAUTILUS_CONFIG (caminho do YAML) e NAUTILUS_KEY (chave que decifra as senhas — obrigatória se houver password: enc:...). Nenhum outro valor é lido do ambiente.

Exemplo de trecho JSON (Cursor, VS Code com MCP, etc.):

{
  "mcpServers": {
    "nautilus": {
      "command": "npx",
      "args": ["-y", "nautilus-mcp-server@latest"],
      "env": {
        "NAUTILUS_CONFIG": "C:/caminho/para/nautilus.yaml",
        "NAUTILUS_KEY": "a-chave-gerada-por-nautilus-keygen"
      }
    }
  }
}

Cursor

Configurações → MCP (ou JSON de MCP do projeto): adicione o servidor com command, args e env como acima.

Claude Desktop

Use o mesmo esquema de command, args e env no arquivo de configuração MCP do aplicativo. Caminho e formato exato variam por sistema; veja a documentação da Anthropic sobre MCP.

Claude Code e outras IDEs

Mesma ideia: processo npx (ou Node apontando para o pacote instalado), argumentos -y e nautilus-mcp-server@latest, e o mesmo bloco de variáveis de ambiente.

Problemas comuns no Windows com npx

Se aparecer EPERM, TAR_ENTRY_ERROR ou MODULE_NOT_FOUND (por exemplo em dependências sob o cache do npm), feche o cliente MCP, apague a pasta %LocalAppData%\npm-cache\_npx e tente de novo. Outra opção estável é instalar o pacote globalmente (npm install -g nautilus-mcp-server) e configurar o MCP para executar o node com o caminho do cli.js dessa instalação global, em vez de npx.