@lucasfroque/db-cli

MCP server e CLI para consulta segura de bancos de dados SQL por agentes de IA. Suporta SQL Server, MySQL e Firebird — somente leitura, credenciais nunca expostas.

Tools MCP disponíveis

| Tool | Descrição | |---|---| | db_query | Executa SELECT e retorna resultado em CSV | | db_list_connections | Lista aliases de conexão (sem expor credenciais) | | db_list_tables | Lista tabelas de uma conexão | | db_describe_table | Retorna schema de uma tabela (colunas, tipos, nullable) |

1. Criar o arquivo de configuração

Crie o arquivo db-cli.config.json com suas credenciais de banco:

{
  "defaultConnection": "meu-banco",
  "pool": {
    "connectionLimit": 10,
    "idleTimeoutMs": 30000,
    "maxIdle": 5,
    "queueLimit": 20
  },
  "query": {
    "defaultRowLimit": 100,
    "maxRowLimit": 1000
  },
  "connections": [
    {
      "alias": "meu-banco",
      "driver": "sqlserver",
      "host": "localhost",
      "port": 1433,
      "database": "MinhaDatabase",
      "user": "db_readonly",
      "password": "CHANGE_ME"
    },
    {
      "alias": "meu-mysql",
      "driver": "mysql",
      "host": "localhost",
      "port": 3306,
      "database": "meu_db",
      "user": "readonly",
      "password": "CHANGE_ME"
    },
    {
      "alias": "meu-firebird",
      "driver": "firebird",
      "host": "localhost",
      "port": 3050,
      "database": "/data/mydb.fdb",
      "user": "readonly",
      "password": "CHANGE_ME"
    }
  ]
}

Salve o arquivo em um local seguro, por exemplo:

• Linux/macOS: ~/.db-cli/config.json
• Windows: %USERPROFILE%\.db-cli\config.json

Restringir permissões (recomendado)

# Linux/macOS
chmod 600 ~/.db-cli/config.json

# Windows (PowerShell)
icacls "$env:USERPROFILE\.db-cli\config.json" /inheritance:r /grant:r "${env:USERNAME}:R"

Criar usuário read-only no banco

SQL Server:

CREATE LOGIN db_readonly WITH PASSWORD = 'senha_segura';
CREATE USER db_readonly FOR LOGIN db_readonly;
GRANT SELECT ON SCHEMA::dbo TO db_readonly;

MySQL:

CREATE USER 'readonly'@'%' IDENTIFIED BY 'senha_segura';
GRANT SELECT ON meu_db.* TO 'readonly'@'%';
FLUSH PRIVILEGES;

Firebird:

-- No Security Database:
CREATE USER READONLY PASSWORD 'senha_segura';
-- No banco alvo:
GRANT SELECT ON TABLE minha_tabela TO READONLY;

2. Configurar o MCP

O pacote é instalado automaticamente via npx — não é necessário instalar nada manualmente.

A variável de ambiente DB_CLI_CONFIG aponta para o seu arquivo de configuração.

Claude Desktop

Arquivo: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) ou %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "db-cli": {
      "command": "npx",
      "args": ["-y", "@lucasfroque/db-cli", "mcp"],
      "env": {
        "DB_CLI_CONFIG": "/home/usuario/.db-cli/config.json"
      }
    }
  }
}

Windows: use C:\\Users\\SeuUsuario\\.db-cli\\config.json

OpenCode

Arquivo: .opencode/config.json na raiz do projeto ou ~/.config/opencode/config.json

{
  "mcp": {
    "servers": {
      "db-cli": {
        "command": "npx",
        "args": ["-y", "@lucasfroque/db-cli", "mcp"],
        "env": {
          "DB_CLI_CONFIG": "/home/usuario/.db-cli/config.json"
        },
        "type": "local"
      }
    }
  }
}

Antigravity (Gemini CLI / Google AI Studio Agent)

Arquivo: mcp_config.json no diretório de configuração do Antigravity

{
  "mcpServers": {
    "db-cli": {
      "command": "npx",
      "args": ["-y", "@lucasfroque/db-cli", "mcp"],
      "env": {
        "DB_CLI_CONFIG": "C:\\Users\\SeuUsuario\\.db-cli\\config.json"
      }
    }
  }
}

Gemini CLI

Arquivo: ~/.gemini/settings.json

{
  "mcpServers": {
    "db-cli": {
      "command": "npx",
      "args": ["-y", "@lucasfroque/db-cli", "mcp"],
      "env": {
        "DB_CLI_CONFIG": "/home/usuario/.db-cli/config.json"
      }
    }
  }
}

Codex (OpenAI)

Arquivo: ~/.codex/config.json

{
  "mcpServers": [
    {
      "name": "db-cli",
      "command": "npx",
      "args": ["-y", "@lucasfroque/db-cli", "mcp"],
      "env": {
        "DB_CLI_CONFIG": "/home/usuario/.db-cli/config.json"
      }
    }
  ]
}

3. Verificar instalação

Para confirmar que o servidor MCP sobe corretamente, execute:

npx @lucasfroque/db-cli --version

E para iniciar o servidor manualmente e inspecionar a resposta JSON-RPC:

npx @lucasfroque/db-cli mcp

4. (Opcional) Daemon para múltiplos agentes

Se múltiplos agentes acessarem o mesmo banco simultaneamente, inicie o daemon para compartilhar os pools de conexão:

npx @lucasfroque/db-cli daemon start
npx @lucasfroque/db-cli daemon status
npx @lucasfroque/db-cli daemon stop

Uso via CLI

# Listar conexões
npx @lucasfroque/db-cli connections list

# Executar query
npx @lucasfroque/db-cli query "SELECT TOP 10 * FROM clientes"

# Especificar conexão
npx @lucasfroque/db-cli query "SELECT * FROM pedidos LIMIT 5" --connection meu-mysql

Segurança

• Apenas SELECT, WITH, EXPLAIN e SHOW são permitidos — qualquer INSERT, UPDATE, DELETE, DROP, etc. é bloqueado automaticamente
• Credenciais nunca são expostas via tools MCP (db_list_connections retorna apenas aliases)
• O limite máximo de linhas (maxRowLimit) é sempre respeitado, independentemente do que o agente solicitar