MariaDB / MySQL

Servidor MCP MariaDB / MySQL

Este servidor MCP expõe bancos de dados MariaDB e MySQL para clientes MCP, como Claude Desktop, VS Code e outras ferramentas compatíveis.

Ele fornece ferramentas para:

• listar bancos de dados disponíveis
• listar tabelas em um banco de dados
• descrever esquemas de tabelas
• executar consultas SQL

Recursos

• Comportamento seguro por padrão: acesso somente leitura é habilitado por padrão
• Validação de consultas para bloquear declarações não permitidas e reduzir risco de injeção
• Permissões de escrita configuráveis por meio de variáveis de ambiente
• Proteção de tempo limite e limite de linhas
• Segurança numérica para IDs de inserção e valores BIGINT retornados pelo driver MariaDB

Instalação

Opção 1: Instalar a partir do npm

npm install -g mariadb-mcp-server

Opção 2: Instalar localmente

npm install mariadb-mcp-server

Opção 3: Compilar a partir do código-fonte

git clone https://github.com/rjsalgado/mariadb-mcp-server.git
cd mariadb-mcp-server
npm install
npm run build

Configuração

Defina as seguintes variáveis de ambiente antes de iniciar o servidor:

• MARIADB_HOST: Host do banco de dados
• MARIADB_PORT: Porta do banco de dados (padrão: 3306)
• MARIADB_USER: Nome de usuário do banco de dados
• MARIADB_PASSWORD: Senha do banco de dados
• MARIADB_DATABASE: Nome padrão do banco de dados (opcional)
• MARIADB_ALLOW_INSERT: Habilitar declarações INSERT (true/false)
• MARIADB_ALLOW_UPDATE: Habilitar declarações UPDATE (true/false)
• MARIADB_ALLOW_DELETE: Habilitar declarações DELETE (true/false)
• MARIADB_TIMEOUT_MS: Tempo limite de consulta em milissegundos (padrão: 10000)
• MARIADB_ROW_LIMIT: Número máximo de linhas retornadas (padrão: 1000)

Exemplo:

export MARIADB_HOST=localhost
export MARIADB_PORT=3306
export MARIADB_USER=myuser
export MARIADB_PASSWORD=mypassword
export MARIADB_DATABASE=mydb
export MARIADB_ALLOW_INSERT=false
export MARIADB_ALLOW_UPDATE=false
export MARIADB_ALLOW_DELETE=false
export MARIADB_TIMEOUT_MS=10000
export MARIADB_ROW_LIMIT=1000

Configuração do MCP

Usando o pacote npm

{
  "mcpServers": {
    "mariadb": {
      "command": "npx",
      "args": ["mariadb-mcp-server"],
      "env": {
        "MARIADB_HOST": "your-host",
        "MARIADB_PORT": "3306",
        "MARIADB_USER": "your-user",
        "MARIADB_PASSWORD": "your-password",
        "MARIADB_DATABASE": "your-database",
        "MARIADB_ALLOW_INSERT": "false",
        "MARIADB_ALLOW_UPDATE": "false",
        "MARIADB_ALLOW_DELETE": "false",
        "MARIADB_TIMEOUT_MS": "10000",
        "MARIADB_ROW_LIMIT": "1000"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Usando um servidor local compilado

{
  "mcpServers": {
    "mariadb": {
      "command": "node",
      "args": ["/absolute/path/to/mariadb-mcp-server/dist/index.js"],
      "env": {
        "MARIADB_HOST": "your-host",
        "MARIADB_PORT": "3306",
        "MARIADB_USER": "your-user",
        "MARIADB_PASSWORD": "your-password",
        "MARIADB_DATABASE": "your-database",
        "MARIADB_ALLOW_INSERT": "false",
        "MARIADB_ALLOW_UPDATE": "false",
        "MARIADB_ALLOW_DELETE": "false",
        "MARIADB_TIMEOUT_MS": "10000",
        "MARIADB_ROW_LIMIT": "1000"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Ferramentas disponíveis

O servidor registra as seguintes ferramentas MCP:

list_databases

Lista todos os bancos de dados acessíveis ao usuário configurado.

list_tables

Lista tabelas de um banco de dados específico.

Parâmetros:

• database (opcional): nome do banco de dados a ser inspecionado

describe_table

Retorna o esquema de uma tabela específica.

Parâmetros:

• database (opcional): nome do banco de dados
• table (obrigatório): nome da tabela

execute_query

Executa uma consulta SQL.

Parâmetros:

• database (opcional): nome do banco de dados
• query (obrigatório): declaração SQL a ser executada

Testes

O repositório inclui scripts para validar o servidor contra uma instância MariaDB ou MySQL.

npm run test:setup
npm run test:tools

Ou execute tudo junto:

npm test

Observações

• O servidor é seguro por padrão e só permite operações somente leitura, a menos que os sinalizadores de escrita sejam explicitamente habilitados.
• Operações de escrita ainda estão sujeitas à validação de consultas e limites de tempo de execução.

Solução de problemas

Se você encontrar problemas:

1. Verifique os logs do servidor para mensagens de erro
2. Verifique suas credenciais e detalhes de conexão do MariaDB/MySQL
3. Garanta que seu usuário MariaDB/MySQL tenha permissões apropriadas
4. Verifique se sua consulta é somente leitura e está formatada corretamente

Inspiração https://github.com/dpflucas/mysql-mcp-server

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para obter detalhes.