Database Explorer MCP

관계형 데이터베이스를 탐색하고 안전하게 쿼리하기 위한 FastMCP 서버입니다. 로컬 개발 데이터베이스는 SQLite이며, SQLAlchemy는 해당 드라이버를 통해 PostgreSQL과 MySQL도 지원합니다.

아키텍처

MCP 클라이언트는 자연어 추론을 수행하고 SQL을 생성합니다. 이 서버는 데이터베이스 도구를 노출하고, 읽기 전용 쿼리를 검증하며, 이를 실행하고 구조화된 결과를 반환합니다.

MCP client LLM -> FastMCP tools -> safety layer -> SQLAlchemy -> database

이 서버는 Anthropic을 호출하지 않으므로 Anthropic API 키가 필요하지 않습니다.

Related MCP server: nl2sql-mcp

설정

uv를 설치한 후 이 디렉터리에서 다음을 실행하세요:

uv sync
uv run python tests/seed_test_db.py
uv run pytest

uv가 아직 PATH에 없다면 다음을 사용하세요:

py -m uv sync
py -m uv run pytest

기본 데이터베이스는 다음과 같습니다:

sqlite:///sample.db

다른 데이터베이스를 사용하려면 서버를 시작하기 전에 DATABASE_URL을 설정하세요. 예:

$env:DATABASE_URL = "sqlite:///C:/data/example.db"
$env:DATABASE_URL = "postgresql+psycopg2://user:password@localhost:5432/example"
$env:DATABASE_URL = "mysql+pymysql://user:password@localhost:3306/example"

MCP 서버 실행

uv run server.py

공유 가능한 VS Code MCP 구성은 .vscode/mcp.json에 있습니다. stdio를 통해 서버를 시작하며 MCP 호환 클라이언트 및 Inspector와 함께 사용할 수 있습니다.

원격 호스팅의 경우 Streamable HTTP를 사용하세요:

$env:MCP_TRANSPORT = "streamable-http"
$env:MCP_HOST = "0.0.0.0"
$env:MCP_PORT = "8000"
uv run server.py

원격 배포는 인증을 제공하고 비밀 구성을 통해 DATABASE_URL을 보호해야 합니다.

도구

• explore_schema: 테이블 목록을 표시하거나 하나의 테이블을 검사합니다

• execute_query: 안전한 읽기 전용 SELECT 하나를 실행합니다

• explain_query: 네이티브 실행 계획을 반환합니다

• validate_schema: 누락된 기본 키와 인덱스가 없는 외래 키를 보고합니다

• suggest_index: 테이블 메타데이터 또는 쿼리 계획에서 인덱스를 제안합니다

• migration_context: 클라이언트 측 마이그레이션 생성을 위한 스키마 컨텍스트를 제공합니다

• validate_migration: 제안된 UP 및 DOWN 스크립트를 실행하지 않고 검증합니다

모든 쿼리 실행과 설명은 안전 계층을 통과합니다. 변경 구문, 주석, 다중 구문은 거부됩니다. 쿼리 결과는 기본적으로 최대 100행으로 제한됩니다.

테스트

uv run pytest

테스트 스위트는 임시 SQLite 데이터베이스를 사용하며 외부 자격 증명이나 실행 중인 데이터베이스 서버가 필요하지 않습니다.

원격 배포

FastMCP Horizon 배포 단계, 원격 데이터베이스 요구 사항 및 인증 체크리스트는 DEPLOYMENT.md를 참조하세요.