MCP MariaDB Server

Gerencie e consulte bancos de dados MariaDB usando o Model Context Protocol (MCP), com suporte para SQL e busca vetorial.

GitHub

202

Experimente este MCPPatrocinado

Documentação

Servidor MCP MariaDB

O Servidor MCP MariaDB fornece uma interface de Protocolo de Contexto de Modelo (MCP) para gerenciar e consultar bancos de dados MariaDB, suportando tanto operações SQL padrão quanto busca avançada baseada em vetores/embeddings. Projetado para uso com assistentes de IA, permite integração perfeita de fluxos de trabalho de dados orientados por IA com bancos de dados relacionais e vetoriais.

Sumário

Visão Geral
Componentes Principais
Ferramentas Disponíveis
Embeddings e Armazenamento Vetorial
Configuração e Variáveis de Ambiente
Considerações de Segurança
Instalação e Configuração
Exemplos de Uso
Integração - Claude desktop/Cursor/Windsurf
Registro de Logs
Testes

Visão Geral

O Servidor MCP MariaDB expõe um conjunto de ferramentas para interagir com bancos de dados MariaDB e armazenamentos vetoriais através de um protocolo padronizado. Ele suporta:

Listagem de bancos de dados e tabelas
Recuperação de esquemas de tabelas
Execução de consultas SQL seguras e somente leitura
Criação e gerenciamento de armazenamentos vetoriais para busca baseada em embeddings
Integração com provedores de embeddings (atualmente OpenAI, Gemini e HuggingFace) (opcional)

Componentes Principais

server.py: Lógica principal do servidor MCP e definições de ferramentas.
config.py: Carrega configuração do ambiente e arquivos .env.
embeddings.py: Gerencia integração com serviços de embeddings (OpenAI).
tests/: Documentação e scripts de testes manuais e automatizados.

Ferramentas Disponíveis

Ferramentas Padrão de Banco de Dados

list_databases
- Lista todos os bancos de dados acessíveis.
- Parâmetros: Nenhum
list_tables
- Lista todas as tabelas em um banco de dados especificado.
- Parâmetros: database_name (string, obrigatório)
get_table_schema
- Recupera o esquema de uma tabela (colunas, tipos, chaves, etc.).
- Parâmetros: database_name (string, obrigatório), table_name (string, obrigatório)
get_table_schema_with_relations
- Recupera o esquema com relações de chave estrangeira para uma tabela.
- Parâmetros: database_name (string, obrigatório), table_name (string, obrigatório)
execute_sql
- Executa uma consulta SQL somente leitura (SELECT, SHOW, DESCRIBE).
- Parâmetros: sql_query (string, obrigatório), database_name (string, opcional), parameters (lista, opcional)
- Nota: Impõe modo somente leitura se MCP_READ_ONLY estiver habilitado.
create_database
- Cria um novo banco de dados se ele não existir.
- Parâmetros: database_name (string, obrigatório)

Ferramentas de Armazenamento Vetorial e Embeddings (opcional)

Nota: Essas ferramentas estão disponíveis apenas quando EMBEDDING_PROVIDER está configurado. Se nenhum provedor de embeddings estiver definido, essas ferramentas serão desabilitadas.

create_vector_store
- Cria um novo armazenamento vetorial (tabela) para embeddings.
- Parâmetros: database_name, vector_store_name, model_name (opcional), distance_function (opcional, padrão: cosine)
delete_vector_store
- Exclui um armazenamento vetorial (tabela).
- Parâmetros: database_name, vector_store_name
list_vector_stores
- Lista todos os armazenamentos vetoriais em um banco de dados.
- Parâmetros: database_name
insert_docs_vector_store
- Insere documentos em lote (e metadados opcionais) em um armazenamento vetorial.
- Parâmetros: database_name, vector_store_name, documents (lista de strings), metadata (lista opcional de dicionários)
search_vector_store
- Realiza busca semântica por documentos semelhantes usando embeddings.
- Parâmetros: database_name, vector_store_name, user_query (string), k (opcional, padrão: 7)

Embeddings e Armazenamento Vetorial

Visão Geral

O Servidor MCP MariaDB fornece capacidades opcionais de embeddings e armazenamento vetorial. Esses recursos podem ser habilitados configurando um provedor de embeddings, ou completamente desabilitados se você precisar apenas de operações padrão de banco de dados.

Provedores Suportados

OpenAI
Gemini
Modelos abertos do Huggingface

Configuração

EMBEDDING_PROVIDER: Defina como openai, gemini, huggingface, ou deixe não definido para desabilitar
OPENAI_API_KEY: Obrigatório se usar embeddings OpenAI
GEMINI_API_KEY: Obrigatório se usar embeddings Gemini
HF_MODEL: Obrigatório se usar embeddings HuggingFace (ex.: "intfloat/multilingual-e5-large-instruct" ou "BAAI/bge-m3")

Seleção de Modelo

Modelos padrão e permitidos são configuráveis no código (DEFAULT_OPENAI_MODEL, ALLOWED_OPENAI_MODELS)
O modelo pode ser selecionado por solicitação ou usa o padrão do modelo configurado

Esquema do Armazenamento Vetorial

Uma tabela de armazenamento vetorial tem as seguintes colunas:

id: Chave primária de incremento automático
document: Texto do documento
embedding: Tipo VECTOR (indexado para busca por similaridade)
metadata: JSON (metadados opcionais)

Configuração e Variáveis de Ambiente

Toda a configuração é feita via variáveis de ambiente (normalmente definidas em um arquivo .env):

Variável	Descrição	Obrigatório	Padrão
`DB_HOST`	Endereço do host MariaDB	Sim	`localhost`
`DB_PORT`	Porta MariaDB	Não	`3306`
`DB_USER`	Nome de usuário MariaDB	Sim
`DB_PASSWORD`	Senha MariaDB	Sim
`DB_NAME`	Banco de dados padrão (opcional; pode ser definido por consulta)	Não
`DB_CHARSET`	Conjunto de caracteres para conexão com o banco de dados (ex.: `cp1251`)	Não	Padrão MariaDB
`DB_SSL`	Habilitar SSL/TLS para conexão com o banco de dados (`true`/`false`)	Não	`false`
`DB_SSL_CA`	Caminho para arquivo de certificado CA para verificação SSL	Não
`DB_SSL_CERT`	Caminho para arquivo de certificado do cliente para autenticação SSL	Não
`DB_SSL_KEY`	Caminho para arquivo de chave privada do cliente para autenticação SSL	Não
`DB_SSL_VERIFY_CERT`	Verificar certificado do servidor (`true`/`false`)	Não	`true`
`DB_SSL_VERIFY_IDENTITY`	Verificar identidade do hostname do servidor (`true`/`false`)	Não	`false`
`MCP_READ_ONLY`	Impõe modo SQL somente leitura (`true`/`false`)	Não	`true`
`MCP_BLOCK_SENSITIVE_SHOW`	Bloquear comandos `SHOW` sensíveis (`PROCESSLIST`, `GRANTS`, `VARIABLES`, `MASTER`/`REPLICA STATUS`, `BINARY LOGS`, etc.) que podem vazar texto de consulta entre conexões, credenciais/privilegios, ou topologia de replicação. Defina independentemente de `MCP_READ_ONLY` (`true`/`false`)	Não	`true`
`MCP_MAX_POOL_SIZE`	Tamanho máximo do pool de conexões DB	Não	`10`
`EMBEDDING_PROVIDER`	Provedor de embeddings (`openai`/`gemini`/`huggingface`)	Não	`None`(Desabilitado)
`OPENAI_API_KEY`	Chave de API para embeddings OpenAI	Sim (se EMBEDDING_PROVIDER=openai)
`GEMINI_API_KEY`	Chave de API para embeddings Gemini	Sim (se EMBEDDING_PROVIDER=gemini)
`HF_MODEL`	Modelos abertos do Huggingface	Sim (se EMBEDDING_PROVIDER=huggingface)
`ALLOWED_ORIGINS`	Lista separada por vírgulas de origens permitidas	Não	Lista longa de origens permitidas correspondente ao uso local do servidor
`ALLOWED_HOSTS`	Lista separada por vírgulas de hosts permitidos	Não	`localhost,127.0.0.1`

Observe que se usar 'http' ou 'sse' como transporte, configurar autenticação é importante para segurança se você permitir conexões fora de localhost. Como diferentes organizações usam diferentes métodos de autenticação, o servidor não fornece um método de autenticação padrão. Você precisará configurar seu próprio método de autenticação. Felizmente, o FastMCP fornece uma maneira simples de fazer isso a partir da versão 2.12.1. Veja a documentação do FastMCP para mais informações. Fornecemos um exemplo de configuração abaixo.

Exemplo de arquivo `.env`

Com suporte a Embeddings (OpenAI):

DB_HOST=localhost
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_PORT=3306
DB_NAME=your_default_database

MCP_READ_ONLY=true
MCP_MAX_POOL_SIZE=10

EMBEDDING_PROVIDER=openai
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=AI...
HF_MODEL="BAAI/bge-m3"

Sem suporte a Embeddings:

DB_HOST=localhost
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_PORT=3306
DB_NAME=your_default_database
MCP_READ_ONLY=true
MCP_MAX_POOL_SIZE=10

Com SSL/TLS habilitado:

DB_HOST=your-remote-host.com
DB_USER=your_db_user
DB_PASSWORD=your_db_password
DB_PORT=3306
DB_NAME=your_default_database

# Enable SSL
DB_SSL=true
DB_SSL_CA=~/.mysql/ca-cert.pem
DB_SSL_CERT=~/.mysql/client-cert.pem
DB_SSL_KEY=~/.mysql/client-key.pem
DB_SSL_VERIFY_CERT=true
DB_SSL_VERIFY_IDENTITY=false

MCP_READ_ONLY=true
MCP_MAX_POOL_SIZE=10

Nota sobre Configuração SSL:

Todos os caminhos de certificado SSL suportam ~ para expansão do diretório home
DB_SSL_CA é usado para verificar o certificado do servidor
DB_SSL_CERT e DB_SSL_KEY são usados para autenticação de certificado do cliente (TLS mútuo)
Defina DB_SSL_VERIFY_CERT=false apenas para testes com certificados autoassinados
Defina DB_SSL_VERIFY_IDENTITY=true para habilitar verificação estrita de hostname

Exemplo de Configuração de Autenticação: Esta configuração usa autenticação web externa via GitHub ou Google. Se você tiver autenticação JWT interna (desejada para organizações que gerenciam seus próprios serviços), você pode usar o provedor JWT.

# GitHub OAuth
export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.github.GitHubProvider
export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_ID="Ov23li..."
export FASTMCP_SERVER_AUTH_GITHUB_CLIENT_SECRET="github_pat_..."

# Google OAuth
export FASTMCP_SERVER_AUTH=fastmcp.server.auth.providers.google.GoogleProvider
export FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_ID="123456.apps.googleusercontent.com"
export FASTMCP_SERVER_AUTH_GOOGLE_CLIENT_SECRET="GOCSPX-..."

Privilégios de Usuário do Banco de Dados - IMPORTANTE

⚠️ A única maneira de garantir 100% de acesso somente leitura com certeza absoluta é configurar o usuário MariaDB com privilégios apropriados. O sinalizador READ_ONLY é uma tentativa de melhor esforço para prevenir operações de escrita, mas é baseado em uma lista de permissões de consultas permitidas e contra um usuário verdadeiramente adversário não é um substituto para privilégios adequados de usuário do banco de dados.

Para uso em produção, você deve criar um usuário de banco de dados dedicado com privilégios mínimos. Isso também é recomendado para mostrar ao LLM apenas os dados que ele pode precisar para executar sua tarefa, mesmo fora do modo somente leitura.

Instalação e Configuração

Requisitos

Python 3.11 (veja .python-version)
uv (gerenciador de dependências; instruções de instalação)
Servidor MariaDB (local ou remoto)

Passos

Clone o repositório
Instale uv (se ainda não estiver):
```
pip install uv
```
Instale as dependências
```
uv lock
uv sync
```
Crie .env na raiz do projeto (veja Configuração)

Execute o servidor

Entrada/Saída Padrão (padrão):

uv run server.py

Transporte SSE:

uv run server.py --transport sse --host 127.0.0.1 --port 9001

Transporte HTTP (HTTP transmissível):

uv run server.py --transport http --host 127.0.0.1 --port 9001 --path /mcp

Exemplos de Uso

Consulta SQL Padrão

{
  "tool": "execute_sql",
  "parameters": {
    "database_name": "test_db",
    "sql_query": "SELECT * FROM users WHERE id = %s",
    "parameters": [123]
  }
}

Criar Armazenamento Vetorial

{
  "tool": "create_vector_store",
  "parameters": {
    "database_name": "test_db",
    "vector_store_name": "my_vectors",
    "model_name": "text-embedding-3-small",
    "distance_function": "cosine"
  }
}

Inserir Documentos no Armazenamento Vetorial

{
  "tool": "insert_docs_vector_store",
  "parameters": {
    "database_name": "test_db",
    "vector_store_name": "my_vectors",
    "documents": ["Sample text 1", "Sample text 2"],
    "metadata": [{"source": "doc1"}, {"source": "doc2"}]
  }
}

Busca Semântica

{
  "tool": "search_vector_store",
  "parameters": {
    "database_name": "test_db",
    "vector_store_name": "my_vectors",
    "user_query": "What is the capital of France?",
    "k": 5
  }
}

Integração - Claude desktop/Cursor/Windsurf/VSCode

Opção 1: Comando Direto (stdio)

{
  "mcpServers": {
    "MariaDB_Server": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mariadb-mcp-server/",
        "run",
        "server.py"
        ],
        "envFile": "path/to/mcp-server-mariadb-vector/.env"      
    }
  }
}

Opção 2: Transporte SSE

{
  "servers": {
    "mariadb-mcp-server": {
      "url": "http://{host}:9001/sse",
      "type": "sse"
    }
  }
}

Opção 3: Transporte HTTP

{
  "servers": {
    "mariadb-mcp-server": {
      "url": "http://{host}:9001/mcp",
      "type": "streamable-http"
    }
  }
}

Opção 4: Contêiner Docker

{
  "servers": {
    "mariadb-mcp-server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-p",
        "9001:9001",
        "-e",
        "DB_HOST=",
        "-e",
        "DB_PORT=",
        "-e",
        "DB_USER=",
        "-e",
        "DB_PASSWORD=",
        "-e",
        "DB_NAME=",
        "mariadb-mcp-server",
        "python",
        "src/server.py",
        "--host",
        "0.0.0.0",
        "--transport",
        "stdio"
      ]
    }
  }
}

Registro de Logs

Logs são gravados em logs/mcp_server.log por padrão.
Mensagens de log incluem chamadas de ferramentas, problemas de configuração, erros de embeddings e solicitações de clientes.
O nível de log e a saída podem ser ajustados no código (veja config.py e configuração do logger).

Testes

Testes estão localizados no diretório src/tests/.
Veja src/tests/README.md para uma visão geral.
Testes cobrem tanto operações SQL padrão quanto operações de ferramentas vetoriais/embeddings.

MCP MariaDB Server

Documentação

Servidor MCP MariaDB

Sumário

Visão Geral

Componentes Principais

Ferramentas Disponíveis

Ferramentas Padrão de Banco de Dados

Ferramentas de Armazenamento Vetorial e Embeddings (opcional)

Embeddings e Armazenamento Vetorial

Visão Geral

Provedores Suportados

Configuração

Seleção de Modelo

Esquema do Armazenamento Vetorial

Configuração e Variáveis de Ambiente

Exemplo de arquivo .env

Privilégios de Usuário do Banco de Dados - IMPORTANTE

Para uso em produção, você deve criar um usuário de banco de dados dedicado com privilégios mínimos. Isso também é recomendado para mostrar ao LLM apenas os dados que ele pode precisar para executar sua tarefa, mesmo fora do modo somente leitura.

Instalação e Configuração

Requisitos

Passos

Exemplos de Uso

Consulta SQL Padrão

Criar Armazenamento Vetorial

Inserir Documentos no Armazenamento Vetorial

Busca Semântica

Integração - Claude desktop/Cursor/Windsurf/VSCode

Opção 1: Comando Direto (stdio)

Opção 2: Transporte SSE

Opção 3: Transporte HTTP

Opção 4: Contêiner Docker

Registro de Logs

Testes

Exemplo de arquivo `.env`