MCP MariaDB 서버는 표준 SQL 연산과 고급 벡터/임베딩 기반 검색을 모두 지원하는 모델 컨텍스트 프로토콜(MCP) 인터페이스를 제공합니다. AI 어시스턴트와 함께 사용하도록 설계되어 AI 기반 데이터 워크플로우와 관계형 및 벡터 데이터베이스의 원활한 통합을 가능하게 합니다.

---

목차

• 개요
• 핵심 구성 요소
• 사용 가능한 도구
• 임베딩 및 벡터 스토어
• 구성 및 환경 변수
• 보안 고려사항
• 설치 및 설정
• 사용 사례
• 통합 - Claude 데스크톱/커서/윈드서프
• 로깅
• 시험

---

개요

MCP MariaDB 서버는 표준화된 프로토콜을 통해 MariaDB 데이터베이스 및 벡터 저장소와 상호작용할 수 있는 도구 세트를 제공합니다. 지원:

• 데이터베이스 및 표 목록
• 테이블 스키마 검색
• 안전한 읽기 전용 SQL 쿼리 실행
• 임베딩 기반 검색을 위한 벡터 스토어 생성 및 관리
• 임베딩 제공업체(현재 OpenAI, Gemini, HuggingFace) (선택 사항) 통합

---

핵심 구성 요소

• server.py: 주요 MCP 서버 논리 및 도구 정의.
• config.py: 환경과 .env 파일에서 구성을 불러옵니다.

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
• Core Components
• Available Tools
• Embeddings & Vector Store
• Configuration & Environment Variables
• Security Considerations
• Installation & Setup
• Usage Examples
• Integration - Claude desktop/Cursor/Windsurf
• Logging
• Testing

---

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.