Labsco
MariaDB logo

MCP MariaDB Server

★ 179

from MariaDB

Manage and query MariaDB databases using the Model Context Protocol (MCP), with support for SQL and vector search.

🔥🔥🔥🔥✓ VerifiedAccount requiredAdvanced setup
#automation#database#devops#git#security#memory

MCP MariaDB Server

The MCP MariaDB Server provides a Model Context Protocol (MCP) interface for managing and querying MariaDB databases, supporting both standard SQL operations and advanced vector/embedding-based search. Designed for use with AI assistants, it enables seamless integration of AI-driven data workflows with relational and vector databases.

Table of Contents

Overview

The MCP MariaDB Server exposes a set of tools for interacting with MariaDB databases and vector stores via a standardized protocol. It supports:

  • Listing databases and tables
  • Retrieving table schemas
  • Executing safe, read-only SQL queries
  • Creating and managing vector stores for embedding-based search
  • Integrating with embedding providers (currently OpenAI, Gemini, and HuggingFace) (optional)

Core Components

  • server.py: Main MCP server logic and tool definitions.
  • config.py: Loads configuration from environment and .env files.
  • embeddings.py: Handles embedding service integration (OpenAI).
  • tests/: Manual and automated test documentation and scripts.

Available Tools

Standard Database Tools

  • list_databases

    • Lists all accessible databases.
    • Parameters: None

  • list_tables

    • Lists all tables in a specified database.
    • Parameters: database_name (string, required)

  • get_table_schema

    • Retrieves schema for a table (columns, types, keys, etc.).
    • Parameters: database_name (string, required), table_name (string, required)

  • get_table_schema_with_relations

    • Retrieves schema with foreign key relations for a table.
    • Parameters: database_name (string, required), table_name (string, required)

  • execute_sql

    • Executes a read-only SQL query (SELECT, SHOW, DESCRIBE).
    • Parameters: sql_query (string, required), database_name (string, optional), parameters (list, optional)
    • Note: Enforces read-only mode if MCP_READ_ONLY is enabled.

  • create_database

    • Creates a new database if it doesn't exist.
    • Parameters: database_name (string, required)

Vector Store & Embedding Tools (optional)

Note: These tools are only available when EMBEDDING_PROVIDER is configured. If no embedding provider is set, these tools will be disabled.

  • create_vector_store

    • Creates a new vector store (table) for embeddings.
    • Parameters: database_name, vector_store_name, model_name (optional), distance_function (optional, default: cosine)

  • delete_vector_store

    • Deletes a vector store (table).
    • Parameters: database_name, vector_store_name

  • list_vector_stores

    • Lists all vector stores in a database.
    • Parameters: database_name

  • insert_docs_vector_store

    • Batch inserts documents (and optional metadata) into a vector store.
    • Parameters: database_name, vector_store_name, documents (list of strings), metadata (optional list of dicts)

  • search_vector_store

    • Performs semantic search for similar documents using embeddings.
    • Parameters: database_name, vector_store_name, user_query (string), k (optional, default: 7)

Embeddings & Vector Store

Overview

The MCP MariaDB Server provides optional embedding and vector store capabilities. These features can be enabled by configuring an embedding provider, or completely disabled if you only need standard database operations.

Supported Providers

  • OpenAI
  • Gemini
  • Open models from Huggingface

Configuration

  • EMBEDDING_PROVIDER: Set to openai, gemini, huggingface, or leave unset to disable
  • OPENAI_API_KEY: Required if using OpenAI embeddings
  • GEMINI_API_KEY: Required if using Gemini embeddings
  • HF_MODEL: Required if using HuggingFace embeddings (e.g., "intfloat/multilingual-e5-large-instruct" or "BAAI/bge-m3")

Model Selection

  • Default and allowed models are configurable in code (DEFAULT_OPENAI_MODEL, ALLOWED_OPENAI_MODELS)
  • Model can be selected per request or defaults to the configured model

Vector Store Schema

A vector store table has the following columns:

  • id: Auto-increment primary key
  • document: Text of the document
  • embedding: VECTOR type (indexed for similarity search)
  • metadata: JSON (optional metadata)

Integration - Claude desktop/Cursor/Windsurf/VSCode

Option 1: Direct Command (stdio)

Copy & paste — that's it
{
  "mcpServers": {
    "MariaDB_Server": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/mariadb-mcp-server/",
        "run",
        "server.py"
        ],
        "envFile": "path/to/mcp-server-mariadb-vector/.env"      
    }
  }
}

Option 2: SSE Transport

Copy & paste — that's it
{
  "servers": {
    "mariadb-mcp-server": {
      "url": "http://{host}:9001/sse",
      "type": "sse"
    }
  }
}

Option 3: HTTP Transport

Copy & paste — that's it
{
  "servers": {
    "mariadb-mcp-server": {
      "url": "http://{host}:9001/mcp",
      "type": "streamable-http"
    }
  }
}

Option 4: Docker container

Copy & paste — that's it
{
  "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"
      ]
    }
  }
}

Logging

  • Logs are written to logs/mcp_server.log by default.
  • Log messages include tool calls, configuration issues, embedding errors, and client requests.
  • Log level and output can be adjusted in the code (see config.py and logger setup).

Testing

  • Tests are located in the src/tests/ directory.
  • See src/tests/README.md for an overview.
  • Tests cover both standard SQL and vector/embedding tool operations.