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).

Segredos sempre por ${VAR}. Qualquer valor pode referenciar uma variável de ambiente com ${NOME}; o servidor a resolve do ambiente e falha cedo se ela não existir (a mensagem cita só o nome, nunca o valor). Nunca coloque senha em texto puro no YAML.

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: "${PG_URL}"
    query_timeout_ms: 60000

PostgreSQL por componentes (senha vem do ambiente), não somente-leitura:

connections:
  pg_app:
    type: postgresql
    host: localhost
    port: 5432
    user: myuser
    password: "${PG_APP_PASSWORD}"
    database: mydb
    read_only: false

Redis com teto de operação:

connections:
  cache:
    type: redis
    url: "${REDIS_URL}"
    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: NAUTILUS_CONFIG (caminho do YAML) e os segredos referenciados por ${VAR} dentro dele.

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",
        "PG_APP_PASSWORD": "secret"
      }
    }
  }
}

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.