mcp-dbserver

자체 구축 MCP 서버로, AI 에이전트(Claude Code, Claude Desktop 또는 MCP 호환 클라이언트)에게 세 가지 데이터베이스 엔진(PostgreSQL(pgvector 포함), DynamoDB, MongoDB Atlas(Atlas Vector Search 포함))에 대한 읽기 전용, 보안 범위 지정 액세스를 동시에 제공합니다. 17년 이상의 멀티클라우드 데이터베이스 아키텍처 작업을 AI/에이전트 도구 공간으로 확장한 개인 프로젝트입니다. 목표는 "에이전트가 데이터베이스를 쿼리할 수 있다"는 것이 아니라, 프로덕션 참조 아키텍처가 요구하는 것과 동일한 최소 권한, 심층 방어 원칙을 서비스 대신 LLM인 호출자에게 적용하는 것을 보여주는 것입니다.

이 저장소에는 (현재 또는 이전) 고용주의 데이터, 스키마 또는 비즈니스 로직이 전혀 포함되어 있지 않습니다. 이 프로젝트를 위해 특별히 생성된 공개 또는 합성 데이터만 있습니다.

아키텍처

flowchart LR
    Client["MCP client<br/>(Claude Code / Claude Desktop)"]

    subgraph Server["mcp-dbserver (stdio)"]
        direction TB
        Tools["Fixed tool surface<br/>(no generic 'run query' tool)"]
        Guard["guardrails.py + allowlist.py<br/>read-only + row-limit re-check"]
        Tools --> Guard
    end

    Client -- "MCP tool calls" --> Tools

    Guard --> PG[("PostgreSQL + pgvector<br/>RDS, IAM or password auth")]
    Guard --> DDB[("DynamoDB<br/>fixed table-target registry")]
    Guard --> Mongo[("MongoDB Atlas + Vector Search<br/>fixed collection-target registry")]

데이터베이스로 향하는 모든 화살표는 이름이 지정되고 허용 목록에 등록된 작업입니다. 원시 SQL, 원시 MongoDB 필터 또는 원시 DynamoDB 키 조건이 절대 아닙니다. 전체 설계는 ARCHITECTURE.md를 참조하세요.

Related MCP server: Secure RDS Read-Only MCP Server

보안 모델

이 프로젝트 부분은 일반적인 "에이전트를 데이터베이스에 연결하는" 데모와 차별화하기 위한 것입니다. 전체 세부 사항(가드레일을 설계만 한 것이 아니라 실제로 테스트하여 발견한 두 가지를 포함)은 ARCHITECTURE.md에 있습니다. 요약은 다음과 같습니다.

1. 읽기 전용, 그걸로 끝입니다. v1에서는 어떤 엔진에도 쓰기, 업데이트 또는 삭제 도구가 존재하지 않습니다. 쓰기가 가능한 버전이 언젠가 생긴다면 그것은 자체 위협 모델을 가진 별도의 프로젝트입니다.

2. 테스트를 통해 발견된 문서화된 경계. '쓰기 도구 없음' 가드레일은 에이전트가 MCP 프로토콜을 통해 할 수 있는 일을 제한합니다. 동일한 자격 증명에 대한 독립적인 액세스 권한이 있는 코드 실행 가능 클라이언트(채팅 전용 클라이언트인 Claude Desktop과 달리 Claude Code 같은)를 제한할 수는 없습니다. 테스트에서 Claude Code는 삭제 도구가 없다는 것을 정확히 확인한 다음, 자체 psycopg 스크립트를 작성하여 MCP 서버를 완전히 우회하고 삭제를 직접 시도했습니다. 구성된 데이터베이스 역할에 쓰기 권한이 없었기 때문에 실패했을 뿐입니다. 따라서 코드 실행 가능 클라이언트에 대한 실제 최후의 방어선은 이 코드에 쓰기 메서드가 없다는 것이 아니라 데이터베이스/IAM 수준의 읽기 전용 역할이며, 이는 암묵적으로 두지 않고 명시적으로 문서화되었습니다.

3. 에이전트의 원시 쿼리 없음. 모든 작업은 유형이 지정된 매개변수를 가진 이름이 지정된 허용 목록 형태입니다. 고정 SQL 템플릿(Postgres), 고정 테이블/컬렉션 대상 레지스트리와 유형이 지정된 키(DynamoDB/MongoDB) — 에이전트 입력에서 생성된 필터 문서, 키 조건 표현식 또는 SQL 문자열은 절대 아닙니다. 벡터 검색 도구의 초기 초안은 테이블/컬럼 이름을 직접 인수로 받았으며, 서버가 실제 클라이언트에 연결되기 전에 발견되어 수정되었습니다(f-string 보간을 통한 실제 SQL 주입 표면).

4. 실행 시 심층 방어. 허용 목록에 있는 Postgres 쿼리도 실행 전에 guardrails.py에 의해 다시 검증됩니다(SELECT/WITH가 아닌 모든 것을 거부하고, 스택된 문을 거부하며, 요청된 내용과 관계없이 행 제한 상한을 적용합니다). 또한 모든 연결은 데이터베이스 수준에서 default_transaction_read_only = on을 설정합니다.

5. 자격 증명: 환경 변수만 사용하며, 절대 기록하지 않고, 절대 하드코딩하지 않습니다. RDS IAM 데이터베이스 인증이 지원되며 저장된 Postgres 비밀번호보다 선호됩니다(rds:GenerateDBAuthToken을 통한 연결당 약 15분짜리 새 토큰, 장기 사용 DB 비밀번호가 전혀 없음).

지원되는 엔진 및 도구

각 도구에 대한 전체 설명과 각각을 만든 이유는 ARCHITECTURE.md에 있습니다. semantic_search_documents와 semantic_search_mongodb는 동일한 데모 데이터 세트와 동일한 로컬 임베딩 모델로 실행되며, 이는 pgvector와 Atlas Vector Search 결과를 직접 비교할 수 있도록 하기 위함입니다.

설정

python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cp .env.example .env   # fill in your own, personal, non-work credentials

테스트 스위트를 실행하세요(실제 데이터베이스는 필요하지 않습니다 — 가드레일/허용 목록 로직은 세 엔진 모두 페이크를 대상으로 단위 테스트됩니다):

pytest

MCP 서버를 실행하세요(stdio 전송, Claude Code / Claude Desktop과 함께 로컬에서 사용):

mcp-dbserver

도구는 필수 환경 변수가 설정된 엔진에 대해서만 등록됩니다. 예를 들어 POSTGRES_DSN만 설정하면 Postgres 도구만 나타납니다. 엔진별 모든 변수는 .env.example을 참조하세요.

Postgres 데모 데이터 세트

data/demo_documents.jsonl은 이 프로젝트를 위해 작성된 약 30개의 짧은 소프트웨어/인프라 설명 스니펫으로 구성된 작은 합성 데이터 세트입니다. 이를 로드하고 임베딩을 로컬에서 생성하세요(fastembed의 ONNX 런타임 — 오프라인, 외부 API 키 불필요, torch/torchvision 의존성 없음):

python scripts/load_demo_dataset.py
python scripts/smoke_test_postgres.py      # connectivity + read-only guardrail
python scripts/verify_demo_dataset.py      # row count + semantic search sanity check

DynamoDB

테이블은 환경 변수를 통해 구성되지 않습니다. 액세스 가능한 테이블은 engines/dynamodb.py의 고정 레지스트리(_TABLE_TARGETS)에서 비롯됩니다. *_dynamodb_* 도구를 활성화하려면 AWS_REGION(및 등록된 테이블 ARN에 대해 dynamodb:GetItem/Scan/DescribeTable로 범위가 지정된 표준 AWS 자격 증명을 환경 변수/프로필/인스턴스 역할을 통해)을 설정하세요.

MongoDB Atlas 데모 데이터 세트

Postgres 설정을 그대로 반영합니다 — 동일한 데이터 세트, 동일한 임베딩 모델 — 따라서 결과를 직접 비교할 수 있습니다. MONGODB_URI/MONGODB_DATABASE를 설정하고(기본 제공 read 역할을 가진 Atlas 사용자, readWrite 아님), 그런 다음:

python scripts/load_demo_dataset_mongodb.py    # upserts data + creates the Atlas Vector Search index
python scripts/verify_demo_dataset_mongodb.py  # index builds asynchronously; re-run if search comes back empty

프로젝트 구조

src/mcp_dbserver/
  guardrails.py        # read-only + row-limit enforcement, engine-agnostic
  allowlist.py          # named, parameterized Postgres query registry
  config.py              # env-var credential loading, per engine
  engines/
    postgres.py           # allowlisted queries + pgvector semantic search
    dynamodb.py             # fixed table-target registry, get/scan/count
    mongodb.py                # fixed collection-target registry, get/list/count/$vectorSearch
  server.py             # MCP entrypoint, registers tools per configured engine
tests/                   # guardrail/allowlist/engine unit tests, all three engines (no live DB needed)
scripts/                 # demo dataset loaders/verifiers, Postgres smoke test

프로덕션 규모에서 다르게 했을 점

v1이 의도적으로 해결하지 않는 것이 무엇인지 명확히 밝히는 것은 프로덕션에 완성된 것처럼 가장하는 것보다 더 많은 것을 알려줍니다.

• 클라이언트 ↔ 서버 인증. v1은 stdio를 통해 실행되며 클라이언트가 하위 프로세스로 직접 시작합니다. OS 프로세스 경계가 바로 신뢰 경계이며, 이는 로컬 단일 사용자 사용에는 문제없지만 그 외에는 문제가 됩니다. 네트워크 배포(HTTP/SSE, 둘 이상의 클라이언트가 접근 가능)는 데모 이상이 되려면 엔진별로 범위가 지정된 클라이언트별 API 키와 서버 앞단의 TLS 종료가 필요합니다.

• 관측 가능성. 아직 쿼리 로깅이나 메트릭이 없습니다. 최소한 네트워크 배포 전에는 어떤 명명된 쿼리/작업이 호출되었는지, 언제, 성공했는지 여부 — 의도적으로 매개변수 값이나 행 내용은 절대 기록하지 않아 로그에 데이터의 두 번째 복사본이 조용히 생기는 것을 방지합니다.

• 속도 제한. 구현되지 않았습니다. 서버에 둘 이상의 로컬 stdio 클라이언트가 접근할 수 있게 되면 중요하지만, 부하가 걸렸을 때 발견하기보다는 이름을 붙여 둘 가치가 있는 격차입니다.

• MySQL. v1 범위에서 명시적으로 제외됩니다. 추가된다면 Postgres와 동일한 허용 목록 + 가드레일 패턴을 따를 것입니다 — 새로운 설계는 필요 없고 네 번째 엔진 분량의 배관 작업만 있으면 됩니다.

• DynamoDB/MongoDB 필터 형태 문제는 계획보다 더 단순해졌지, 더 복잡해지지 않았습니다. 원래 설계는 DynamoDB/MongoDB의 허용 목록 필터마다 유형화된 스키마를 고려했습니다. 실제로 출시된 것은 더 작습니다. 고정 대상 레지스트리와 엔진당 고정된 소수의 명명된 작업뿐이며, 일반적인 find(filter) 또는 query(key_condition) 도구가 전혀 없습니다. 검증 DSL을 구축하려는 본능이 더 '인상적으로 들리는' 옵션이었고, 더 단순한 옵션이 동일한 격차를 더 확실하게 메운다는 것이 판명되었기 때문에 언급할 가치가 있습니다 — $where나 임의의 키 조건이 숨을 수 있는 허용적인 형태가 없습니다. 그런 필드가 없기 때문입니다.