Database Server

Um servidor Model Context Protocol (MCP) que fornece capacidades de execução de consultas em múltiplos bancos de dados, com suporte para bancos de dados SQLite, PostgreSQL e MySQL. Inclui uma interface web integrada para gerenciar conexões de banco de dados.

GitHub

Experimente este MCPPatrocinado

Documentação

MCP Database Server

Um servidor Model Context Protocol (MCP) que fornece capacidades de execução de consultas em múltiplos bancos de dados com suporte para SQLite, PostgreSQL e MySQL. Inclui uma Web UI integrada para gerenciar conexões de banco de dados.

Pacote NPM

Disponível no NPM: @ahmetbarut/mcp-database-server

# Use with npx (no installation required)
npx @ahmetbarut/mcp-database-server

# Or install globally
npm install -g @ahmetbarut/mcp-database-server

Recursos

Suporte a Múltiplos Bancos de Dados: SQLite, PostgreSQL e MySQL com conexões reais
Web UI: Interface de navegador integrada para gerenciar conexões de banco de dados
Armazenamento de Configuração SQLite: Todas as configurações de conexão persistidas localmente em ~/.mcp-database-server/connections.db
Conformidade com o Protocolo MCP: Implementação JSON-RPC completa com suporte total a ferramentas
Detecção Automática Inteligente: Seleciona automaticamente a conexão ativa única para consultas
Recuperação de Conexão: Tenta novamente conexões com falha com relatórios de erro detalhados
Segurança em Primeiro Lugar: Consultas parametrizadas, proteção contra injeção de SQL, registro de auditoria
Suporte a SSL: SSL configurável por conexão
Segurança de Tipos: Implementação TypeScript completa com validação Zod
Compatível com Node.js v23: Funciona com as versões mais recentes do Node.js

Início Rápido

npx @ahmetbarut/mcp-database-server

O servidor inicia e a Web UI abre em http://localhost:3693. Adicione suas conexões de banco de dados pelo navegador.

Web UI

A Web UI integrada fornece uma interface visual para gerenciar conexões de banco de dados:

Adicionar/Editar/Excluir conexões de banco de dados (SQLite, PostgreSQL, MySQL)
Testar conexões antes de salvar
Alternância de SSL para bancos de dados de rede
Armazenamento persistente — as conexões sobrevivem a reinicializações do servidor

Acesse em http://localhost:3693 quando o servidor estiver em execução.

Variáveis de Ambiente

Variável	Padrão	Descrição
`WEB_UI_PORT`	`3693`	Porta da Web UI
`WEB_UI_ENABLED`	`true`	Ativar/desativar Web UI
`LOG_LEVEL`	`info`	Nível de registro (`debug`, `info`, `warn`, `error`)

Configuração do Cliente MCP

Claude Desktop

Adicione ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@ahmetbarut/mcp-database-server"]
    }
  }
}

Cursor IDE

Adicione ao ~/.cursor/mcp.json:

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@ahmetbarut/mcp-database-server"]
    }
  }
}

Porta Personalizada

{
  "mcpServers": {
    "database": {
      "command": "npx",
      "args": ["-y", "@ahmetbarut/mcp-database-server"],
      "env": {
        "WEB_UI_PORT": "4000"
      }
    }
  }
}

Após iniciar, abra a Web UI no seu navegador para adicionar conexões de banco de dados.

Ferramentas MCP

`execute_query`

Execute consultas SQL em uma conexão de banco de dados com suporte a consultas parametrizadas.

{
  "connection_name": "my-postgres",
  "query": "SELECT * FROM users WHERE status = $1",
  "parameters": ["active"]
}

`list_databases`

Lista bancos de dados de uma conexão específica ou de todas as conexões configuradas. Suporta detecção automática inteligente quando apenas uma conexão está ativa.

{
  "connection_name": "my-postgres"
}

`list_connections`

Lista todas as conexões de banco de dados com status e detalhes.

{
  "include_credentials": false
}

`retry_failed_connections`

Tenta novamente conexões de banco de dados com falha.

{
  "connection_name": "my-postgres"
}

Configuração de Conexão

Todas as conexões de banco de dados são gerenciadas através da Web UI e armazenadas em um banco de dados SQLite local em ~/.mcp-database-server/connections.db.

Tipos de Banco de Dados Suportados

SQLite

Caminho para o arquivo do banco de dados

PostgreSQL

Host, porta, banco de dados, usuário, senha
Suporte a SSL (opcional)

MySQL

Host, porta, banco de dados, usuário, senha
Suporte a SSL (opcional)

Configurações de Conexão

Configuração	Padrão	Descrição
`maxConnections`	`10`	Tamanho máximo do pool de conexões
`timeout`	`30000`	Tempo limite de conexão em milissegundos
`ssl`	`false`	Ativar SSL para a conexão

Desenvolvimento

# Clone the repository
git clone https://github.com/ahmetbarut/mcp-database-server.git
cd mcp-database-server

# Install dependencies
npm install

# Development mode (hot-reload)
npm run dev

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint
npm run lint

# Type check
npm run type-check

Estrutura do Projeto

mcp-database-server/
├── src/
│   ├── index.ts              # CLI entry point
│   ├── server/
│   │   └── mcp-server.ts     # MCP server, tool handlers
│   ├── database/
│   │   ├── base.ts           # Abstract base driver
│   │   ├── factory.ts        # Driver factory & connection manager
│   │   └── drivers/          # SQLite, PostgreSQL, MySQL drivers
│   ├── config/
│   │   ├── settings.ts       # Config manager (loads from SQLite store)
│   │   └── config-store.ts   # SQLite-backed connection storage
│   ├── web/
│   │   ├── web-server.ts     # HTTP server for Web UI
│   │   ├── routes.ts         # REST API endpoints
│   │   └── ui.ts             # Embedded HTML/CSS/JS interface
│   ├── types/                # TypeScript types & Zod schemas
│   └── utils/                # Logger, exceptions, helpers
├── tests/unit/               # Jest test suites
└── dist/                     # Compiled output

Arquitetura

npx @ahmetbarut/mcp-database-server
    │
    ├── MCPDatabaseServer
    │   ├── MCP stdio transport (JSON-RPC)
    │   ├── DatabaseConnectionManager
    │   └── WebUIServer (http://localhost:3693)
    │
    └── ConnectionConfigStore (~/.mcp-database-server/connections.db)
        └── SQLite database with connection configs

Armazenamento de Configuração carrega conexões salvas do banco SQLite local
Gerenciador de Conexões inicializa os drivers de banco de dados para cada configuração
Servidor MCP expõe ferramentas via JSON-RPC sobre stdio
Web UI fornece CRUD baseado em navegador para conexões via API REST

Segurança

Consultas parametrizadas — previne injeção de SQL
Mascaramento de credenciais — senhas ocultas na saída de list_connections
Registro de auditoria — todas as operações registradas via Winston
Validação de entrada — esquemas Zod para toda a configuração

Testes

Test Suites: 2 passed, 2 total
Tests:       23 passed, 23 total

npm test               # Run all tests
npm run test:watch     # Watch mode
npm run test:coverage  # Coverage report

Solução de Problemas

Web UI inacessível

Verifique se a porta 3693 já está em uso
Tente uma porta diferente: WEB_UI_PORT=4000

Falha na conexão

Use o botão "Testar Conexão" na Web UI antes de salvar
Verifique se o servidor de banco de dados está em execução e acessível
Verifique as credenciais e a conectividade de rede
Para PostgreSQL: desative o SSL se o servidor não o suportar

O cliente MCP não consegue conectar

Garanta que npx @ahmetbarut/mcp-database-server seja executado sem erros
Reinicie o cliente MCP após alterações de configuração
Verifique os logs do cliente MCP para detalhes do erro

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Contribuição

Siga os padrões de codificação TypeScript
Adicione testes para novas funcionalidades
Atualize a documentação para alterações de API
Siga as diretrizes de segurança

Suporte

Para problemas e dúvidas, use o rastreador de problemas do GitHub.