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 SCAN (padrão, cursor, max_keys, max_scan_iterations), investigação em db_get_metadata (tipo, TTL, cardinalidade, memória, amostra incremental via HSCAN/SSCAN), leitura em db_read_cache com truncagem por bytes; comandos respeitam NAUTILUS_QUERY_TIMEOUT_MS.

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; limites globais de tamanho de query, timeout e número de linhas/registros podem ser ajustados por variáveis de ambiente (veja abaixo).

Tools

| Tool | Função | |------|--------| | db_list_connections | Lista os connection_id configurados, tipo de engine e read_only. Use antes das demais tools para escolher o id correto. | | db_list_resources | SQL: tabelas. MongoDB: coleções (database obrigatório). Redis: chaves (key_pattern, cursor, opcional max_keys, max_scan_iterations). | | db_get_metadata | SQL: metadados/colunas. MongoDB: amostra de documentos. Redis: investigação estrutural (max_sample_elements, max_value_bytes, max_scan_iterations opcionais). | | db_describe_indexes | Índices de uma tabela SQL ou de uma coleção MongoDB. | | db_query_sql | Executa SELECT/WITH em conexões SQL. output_format: table, json ou csv; limit opcional (respeitando o teto global). | | db_fetch_documents | MongoDB: find com filter_json, limit e skip. | | db_read_cache | Redis: leitura por tipo; opcional max_elements, max_value_bytes, max_scan_iterations. | | db_peek_sample | Até três registros: linhas (SQL), documentos (MongoDB) ou amostra (Redis). |

Resources (MCP)

| URI | Conteúdo | |-----|----------| | nautilus://connections | JSON com { "connections": [...] } (mesmos campos que db_list_connections: connection_id, type, read_only). |

Como configurar as conexões

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

Todas as variáveis seguem o padrão:

DATABASES__<connection_id>__<atributo>

Obrigatório por conexão

• type: um entre postgresql, mysql, mariadb (tratado como MySQL), sqlite, sqlserver, oracle, mongodb, redis.
• Conexão, em um dos dois formatos:
  • url: URL completa de conexão (ex.: postgresql://user:senha@host:5432/banco, mongodb://host:27017/, redis://host:6379/0, arquivo/path para SQLite conforme documentação do driver).
  • Ou campos separados (útil se a senha tem @, :, /, etc.), sempre no formato DATABASES__<connection_id>__…: host, port, user, password, database ou db. Exemplo com id pg: DATABASES__pg__host, DATABASES__pg__port (ex.: 5432), DATABASES__pg__user, DATABASES__pg__password, DATABASES__pg__database. Em vez de port separado, a porta pode ir junto em host (ex.: db.exemplo.com:3306). Se port for omitida e não estiver no host, usam-se portas padrão por tipo (PostgreSQL 5432, MySQL 3306, SQL Server 1433, Oracle 1521, MongoDB 27017, Redis 6379).

Opcional por conexão

• read_only: padrão é somente leitura.

Limites e opções globais (opcional)

| Variável | Efeito (padrão se omitida) | |----------|----------------------------| | NAUTILUS_QUERY_MAX_LENGTH | Tamanho máximo da query SQL em caracteres (2000). | | NAUTILUS_MAX_ROW_LIMIT ou NAUTILUS_MAX_ROWS | Teto de linhas/registros e validação de LIMIT (200). | | NAUTILUS_DEFAULT_ROW_LIMIT | Limite padrão quando a tool não fixa outro (50, até o máximo). | | NAUTILUS_QUERY_TIMEOUT_MS | Timeout das operações em milissegundos (5000 se não usar a de segundos). | | NAUTILUS_QUERY_TIMEOUT_SECONDS | Alternativa ao timeout em ms (só usada se NAUTILUS_QUERY_TIMEOUT_MS não estiver definida). | | NAUTILUS_READ_ONLY_MODE | Modo somente leitura (true por padrão). | | NAUTILUS_REDIS_MAX_KEYS_PER_SCAN | Máximo de chaves por página no SCAN (padrão 2000; teto absoluto 2000). Também limita db_list_resources junto com NAUTILUS_MAX_ROW_LIMIT. | | NAUTILUS_REDIS_MAX_SCAN_ITERATIONS | Máximo de iterações SCAN/HSCAN/SSCAN por chamada (padrão 10000; entre 100 e 50000). | | NAUTILUS_REDIS_MAX_VALUE_BYTES | Truncagem de strings e valores grandes na resposta (padrão 65536 bytes). |

Exemplos (.env ou env do MCP)

PostgreSQL por URL:

DATABASES__pg__type=postgresql
DATABASES__pg__url=postgresql://user:password@localhost:5432/mydb

PostgreSQL com host e senha com caracteres especiais:

DATABASES__pg__type=postgresql
DATABASES__pg__host=localhost
DATABASES__pg__port=5432
DATABASES__pg__user=myuser
DATABASES__pg__password=pa@ss:word/with
DATABASES__pg__database=mydb

MySQL com host e porta no mesmo campo:

DATABASES__app__type=mysql
DATABASES__app__host=db.exemplo.com:3306
DATABASES__app__user=app
DATABASES__app__password=secret
DATABASES__app__database=appdb

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: todas as DATABASES__… e, se quiser, as NAUTILUS__….

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

{
  "mcpServers": {
    "nautilus": {
      "command": "npx",
      "args": ["-y", "nautilus-mcp-server@latest"],
      "env": {
        "DATABASES__pg__type": "postgresql",
        "DATABASES__pg__host": "localhost",
        "DATABASES__pg__port": "5432",
        "DATABASES__pg__user": "app",
        "DATABASES__pg__password": "secret",
        "DATABASES__pg__database": "appdb"
      }
    }
  }
}

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.

Uso programático (Node)

Chame await initAppContext() antes de usar createMcpServer() — o CLI já faz isso. Sem nenhuma conexão sqlserver nas variáveis DATABASES__*, o pacote não carrega mssql / tedious / js-md4 na inicialização (útil quando só há Postgres, Mongo, Redis, etc.).

Problemas comuns no Windows com npx

Se aparecer EPERM, TAR_ENTRY_ERROR ou MODULE_NOT_FOUND (ex.: bson/mongodb, js-md4/tedious/mssql, ou outro subpacote em npm-cache\_npx), o cache do npx costuma estar corrompido ou incompleto: feche o cliente MCP, apague %LocalAppData%\npm-cache\_npx (toda a pasta) e use de novo npx -y nautilus-mcp-server@latest. Instalação global (npm install -g nautilus-mcp-server@latest) e executar o cli.js com node evita o cache _npx.