postgres-mcp

여러 PostgreSQL 데이터소스를 하나의 Streamable HTTP MCP 서버로 제공하는 작은 Text-to-SQL 백엔드입니다.

AI / MCP client
        |
        | Streamable HTTP: http://host:8000/mcp
        v
postgres-mcp
  ├─ product_quality -> PostgreSQL connection pool
  └─ analytics       -> PostgreSQL connection pool

MCP 호스트의 AI가 자연어를 SQL로 변환합니다. 이 서버는 실제 데이터베이스 구조를 보여 주고, 선택한 데이터소스 한 곳에서 SQL 한 문장을 제한된 트랜잭션으로 실행합니다. 서로 다른 데이터소스를 한 SQL에서 조인하지 않습니다.

MCP 계약

외부 도구는 두 개뿐입니다.

권장 순서:

1. search_objects(object_type="data_source")로 데이터소스를 확인합니다.

2. 기본 스키마가 없으면 object_type="schema"로 스키마를 확인합니다.

3. 관련 테이블이나 뷰의 이름을 찾습니다.

4. 필요한 relation만 detail_level="full"로 조회합니다.

5. 확인된 식별자로 스키마 한정 SQL을 만들고 execute_sql로 실행합니다.

서버가 별도 MCP prompt를 제공하지는 않습니다. 서버 지침과 두 도구의 설명이 위 흐름을 안내합니다.

Related MCP server: PostgreSQL API SSH MCP Server

빠른 시작

Python 3.12 이상과 uv가 필요합니다.

cp postgres-mcp.example.toml postgres-mcp.toml
cp .env.example .env

postgres-mcp.toml에 데이터소스를 정의합니다.

default_source = "product_quality"

[[sources]]
id = "product_quality"
description = "Product quality database"
host = "127.0.0.1"
port = 5433
database = "product_quality"
user_env = "DB_USER"
password_env = "DB_PASSWORD"
default_schema = "public"

호스트, 포트, 데이터베이스처럼 민감하지 않은 연결 정보는 TOML에 두고, 계정 값만 user_env, password_env가 가리키는 환경 변수에 넣습니다.

POSTGRES_MCP_CONFIG=postgres-mcp.toml
DB_USER=readonly
DB_PASSWORD=password

서버는 .env를 자동으로 읽지 않습니다. uv가 명시적으로 환경 변수를 주입하도록 실행합니다.

uv sync --locked
uv run --env-file .env postgres-mcp

기본 엔드포인트:

curl http://127.0.0.1:8000/healthz
curl http://127.0.0.1:8000/readyz

readyz는 데이터베이스 전체에 미리 연결하지 않습니다. 각 연결 풀은 해당 데이터소스를 처음 사용할 때 생성됩니다.

데이터소스 설정

POSTGRES_MCP_CONFIG가 가리키는 TOML 파일만 데이터베이스 설정으로 사용합니다.

선택 설정은 공통 블록으로 우회하지 않고 데이터소스마다 직접 적습니다. 여러 데이터소스가 같은 계정을 사용하면 같은 user_env와 password_env를 재사용합니다. 별도 권한이 필요한 데이터소스만 다른 환경 변수 이름을 지정합니다.

default_source = "product_quality"

[[sources]]
id = "product_quality"
description = "Product quality database"
host = "127.0.0.1"
port = 5433
database = "product_quality"
user_env = "DB_USER"
password_env = "DB_PASSWORD"
default_schema = "public"
pool_size = 2

[[sources]]
id = "analytics"
description = "Quality analytics database"
host = "127.0.0.1"
port = 5433
database = "analytics"
user_env = "DB_USER"
password_env = "DB_PASSWORD"
default_schema = "public"
pool_size = 2

[[sources]]
id = "audit"
description = "Restricted audit database"
host = "audit-db.internal"
database = "quality_audit"
user_env = "AUDIT_DB_USER"
password_env = "AUDIT_DB_PASSWORD"
default_schema = "audit"
pool_size = 1

default_source가 없고 소스가 여러 개면 도구 호출에 data_source를 명시해야 합니다. 소스가 하나면 자동으로 선택됩니다.

현재 구현은 PostgreSQL만 지원합니다. 다른 RDB가 실제 요구사항이 되기 전에는 공통 드라이버 계층이나 adapter 추상화를 두지 않습니다.

Codex 연결

서버를 먼저 실행하고 프로젝트 .codex/config.toml에 URL을 등록합니다.

[mcp_servers.postgres-mcp]
url = "http://127.0.0.1:8000/mcp"
startup_timeout_sec = 10
tool_timeout_sec = 60

새 Codex 세션부터 MCP 연결이 초기화됩니다.

HTTP 설정

MCP 경로는 /mcp, HTTP 모드는 stateless, 응답은 JSON으로 고정됩니다. 다음 운영 설정만 환경 변수로 조정할 수 있습니다.

애플리케이션 로그는 터미널에서 Rich 색상과 읽기 쉬운 레벨·시간 형식으로 표시되고, 비대화형 출력에서는 ANSI 색상을 자동으로 생략합니다. 기본 INFO는 서버와 connection pool 수명주기만 기록합니다. DEBUG는 도구별 처리 시간과 결과 행 수를 추가하지만 SQL, parameter, 자격증명 값은 기록하지 않습니다.

POSTGRES_MCP_HOST=0.0.0.0처럼 외부 인터페이스에 바인드하면 POSTGRES_MCP_ALLOWED_HOSTS를 반드시 지정해야 합니다. 정확한 hostname과 hostname:* 패턴을 사용하고 광범위한 와일드카드는 피하십시오.

Docker

docker build -t postgres-mcp:local .

호스트 머신의 PostgreSQL에 연결한다면 마운트할 TOML의 host를 "host.docker.internal"로 바꿉니다. 127.0.0.1은 컨테이너 자신을 가리킵니다.

docker run --rm -p 8000:8000 \
  --add-host host.docker.internal:host-gateway \
  --mount type=bind,src="$(pwd)/postgres-mcp.toml",dst=/etc/postgres-mcp/postgres-mcp.toml,readonly \
  -e POSTGRES_MCP_CONFIG=/etc/postgres-mcp/postgres-mcp.toml \
  -e DB_USER=readonly \
  -e DB_PASSWORD=password \
  -e POSTGRES_MCP_ALLOWED_HOSTS="localhost,localhost:*,127.0.0.1,127.0.0.1:*" \
  postgres-mcp:local

설정 파일을 이미지에 포함하지 말고 읽기 전용으로 mount하십시오. 운영 환경에서는 TOML의 host에 실제 DB DNS를 사용하고, 계정은 명령줄 대신 런타임 Secret으로 주입하십시오.

Kubernetes

deploy/k8s/postgres-mcp.yaml은 다음을 포함합니다.

• 데이터소스 하나를 정의한 ConfigMap

• POSTGRES_MCP_CONFIG 파일 mount

• Secret의 DB_USER, DB_PASSWORD

• readiness/liveness probe

• 비루트, read-only filesystem 보안 설정

kubectl create secret generic postgres-mcp-secrets \
  --from-literal=db-user='readonly' \
  --from-literal=db-password='password'
kubectl apply -f deploy/k8s/postgres-mcp.yaml
kubectl port-forward service/postgres-mcp 8000:8000

상세한 운영 절차는 docs/deployment.md를 참고하십시오.

연결 위치와 정책은 ConfigMap, 계정 값은 Secret으로 분리합니다. 어느 쪽이든 바뀌면 명시적으로 rollout하여 새 설정과 연결 풀을 함께 적용합니다. 권한, 네트워크, 감사 기준이 같은 데이터베이스만 한 배포에 묶고 보안 경계가 다르면 postgres-mcp 배포도 분리하십시오.

안전 기본값

• 기본 읽기 전용 PostgreSQL 트랜잭션

• prepared statement를 통한 단일 문장 제한

• $1, $2, ... 파라미터 바인딩

• 소스별 행 수, statement timeout, connection timeout

• 큰 정수, 날짜, UUID, bytea의 JSON 안전 변환

• 자격증명을 MCP 입력이나 결과에 노출하지 않음

• Host/Origin 검사로 DNS rebinding 방어

read_only=true는 보조 방어입니다. 운영에서는 각 데이터소스에 필요한 SELECT 권한만 가진 PostgreSQL 역할을 사용하고, 외부 공개 시 TLS와 인증을 담당하는 gateway를 두십시오.

개발

uv sync
uv run pytest
uv run ruff check src tests
uv run ruff format --check src tests
uv run pyright
uv build

구현과 책임 경계는 다음 문서에 정리되어 있습니다.

• docs/architecture-v0.4.0.md

• docs/service-boundaries.md

• docs/code-story-ko.md