db-readonly-mcp

MCP 서버로, AI 어시스턴트(Claude Code, Claude Desktop 또는 다른 MCP 클라이언트)에게 보호된 읽기 전용 Postgres 데이터베이스 접근 권한을 제공합니다. "어제 생성된 모든 판매자 가져와" 같은 요청을 하면 어시스턴트가 SQL을 작성하고 이 서버를 통해 실행하며, 서버는 쿼리가 항상 데이터를 읽기만 할 수 있도록 강제합니다.

Postgres 전용입니다 — 다른 데이터베이스는 지원하지 않습니다.

왜 이게 필요한가

어시스턴트가 데이터베이스에 직접 쿼리하도록 하는 것은 디버깅, 데이터 탐색, 매번 스크립트를 작성하지 않고 "X가 몇 개인지" 질문에 답하는 데 실제로 유용합니다. 위험은 명백합니다: LLM이 환각을 일으키거나 파괴적인 쿼리를 작성하도록 유도될 수 있습니다. 이 서버는 단일 메커니즘에 의존하지 않고 여러 독립적인 보호 계층을 통해 그 위험을 거의 0으로 만들기 위해 존재합니다.

Related MCP server: Postgres Scout MCP

안전 모델

실제로 신뢰되는 순서대로 계층화되어 있습니다:

1. DB 역할 — 연결은 SELECT 전용 권한이 부여된 전용 Postgres 역할을 사용합니다. 이것이 실제 경계입니다: 다른 모든 계층이 우회되더라도 역할은 쓸 수 없습니다.

2. 쿼리 검증 — 단일 SELECT/WITH ... SELECT 문이 아닌 모든 것을 거부합니다(세미콜론으로 연결된 문, DDL/DML 키워드 없음).

3. 강제 LIMIT — 모든 쿼리는 SELECT * FROM (...) LIMIT N으로 감싸지며, 요청된 값과 관계없이 MAX_LIMIT으로 제한됩니다.

4. statement_timeout — 쿼리는 STATEMENT_TIMEOUT_MS 후에 종료됩니다.

5. 시작 로그 — 부팅 시 연결된 데이터베이스/사용자를 stderr에 기록하여, 쿼리가 실행되기 전에 어떤 DB를 가리키고 있는지 명확히 알 수 있습니다.

이 서버는 항상 dev/test/staging 데이터베이스에만 연결하세요 — 절대 프로덕션에는 연결하지 마세요. 계층 2-5는 심층 방어입니다; 계층 1(DB 역할)만 실제로 신뢰해야 하며, 그것조차 프로덕션 데이터로는 신뢰해서는 안 됩니다.

요구 사항

• Node.js >= 20

• 역할을 생성할 수 있는 Postgres 데이터베이스

• MCP 클라이언트(예: Claude Code, Claude Desktop 또는 stdio를 통해 MCP 서버를 지원하는 다른 클라이언트)

설정

1. 클론 및 설치

git clone https://github.com/david-mogbeyi/db-readonly-mcp.git
cd db-readonly-mcp
npm install

2. 읽기 전용 역할 생성

대상 Postgres 데이터베이스에 대해 다음을 실행하세요 — 앱이 public 이외의 스키마/소유자를 사용하는 경우 역할 이름, 비밀번호, 데이터베이스 이름 및 스키마/소유자를 교체하세요:

CREATE ROLE myapp_readonly WITH LOGIN PASSWORD '<choose-a-password>';
GRANT CONNECT ON DATABASE myapp TO myapp_readonly;
GRANT USAGE ON SCHEMA public TO myapp_readonly;
GRANT SELECT ON ALL TABLES IN SCHEMA public TO myapp_readonly;

-- Keeps future tables (new migrations) readable automatically, without
-- re-running this grant every time the schema changes.
ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO myapp_readonly;

스키마가 public이 아니거나 여러 스키마가 있는 경우, 각 스키마에 대해 GRANT USAGE/GRANT SELECT/ALTER DEFAULT PRIVILEGES 줄을 반복하세요. 이 서버는 현재 list_tables/describe_table에 대해서만 public 스키마를 쿼리하지만, query_readonly는 역할에 접근 권한이 부여된 모든 스키마를 참조할 수 있습니다.

3. 구성

cp .env.example .env

.env를 편집하고 DATABASE_URL을 읽기 전용 역할의 연결 문자열로 설정하세요:

DATABASE_URL=postgresql://myapp_readonly:<password>@localhost:5432/myapp

다른 변수는 아래 구성을 참조하세요.

4. 빌드

npm run build

이 명령은 tsc를 통해 src/를 dist/로 컴파일합니다. 변경 사항을 가져오거나 소스를 편집한 후 다시 실행하세요.

MCP 클라이언트에 등록

Claude Code

쿼리하려는 프로젝트에서 .mcp.json을 추가하거나(또는 기존 파일을 편집):

{
  "mcpServers": {
    "db-readonly": {
      "command": "node",
      "args": ["/absolute/path/to/db-readonly-mcp/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://myapp_readonly:<password>@localhost:5432/myapp"
      }
    }
  }
}

/absolute/path/to/db-readonly-mcp를 이 저장소를 클론한 위치로 교체하세요. Claude Code를 다시 시작하거나(또는 MCP 서버를 다시 연결) 변경 사항을 적용하세요.

프로젝트별로 등록하는 대신 전역으로 등록할 수도 있습니다 — claude mcp add 및 범위 옵션은 Claude Code MCP 문서를 참조하세요.

Claude Desktop / 기타 MCP 클라이언트

stdio를 통해 MCP 서버를 지원하는 모든 클라이언트는 동일한 방식으로 사용할 수 있습니다: node /absolute/path/to/db-readonly-mcp/dist/index.js를 가리키고 환경에 DATABASE_URL(및 선택적으로 아래의 다른 환경 변수)을 설정하세요. MCP 서버 구성이 있는 위치는 클라이언트 문서를 참조하세요 — Claude Desktop의 경우 claude_desktop_config.json이며, 위와 동일한 command/args/env 형식을 사용합니다.

구성

모든 구성은 환경 변수를 통해 이루어집니다(로컬 실행의 경우 .env에 설정하거나 MCP 클라이언트 구성의 env 블록에 설정).

도구

서버는 어시스턴트에게 세 가지 도구를 노출합니다:

list_tables

public 스키마의 테이블을 나열합니다. 인수 없음.

→ [
    { "table_name": "merchants" },
    { "table_name": "orders" },
    ...
  ]

describe_table(table)

public 스키마에 있는 테이블의 열, 유형, null 허용 여부 및 기본값.

{ "table": "merchants" }
→ [
    { "column_name": "id", "data_type": "uuid", "is_nullable": "NO", "column_default": "gen_random_uuid()" },
    { "column_name": "created_at", "data_type": "timestamp with time zone", "is_nullable": "NO", "column_default": "now()" },
    ...
  ]

query_readonly(sql, limit?)

단일 보호된 SELECT(또는 WITH ... SELECT) 문을 실행합니다. limit는 선택 사항이며 더 큰 값이 전달되어도 MAX_LIMIT으로 제한됩니다.

{ "sql": "SELECT id, name, created_at FROM merchants WHERE created_at > now() - interval '1 day'" }
→ { "rowCount": 3, "rows": [ { "id": "...", "name": "...", "created_at": "..." }, ... ] }

단일 SELECT/WITH 문이 아닌 모든 것 — 여러 문, DDL, DML, SET 등 — 은 데이터베이스에 도달하기 전에 거부되며, 그 이유가 설명됩니다.

로컬 개발

npm run dev   # runs src/index.ts directly via tsx, loads .env via Node's --env-file

프로젝트 구조

src/
  index.ts    # MCP server setup and tool definitions
  sqlGuard.ts # query validation (layer 2 of the safety model)
  db.ts       # Postgres pool setup (statement_timeout, pool size)
  config.ts   # env var loading/validation

문제 해결

• "DATABASE_URL environment variable is required" — .env가 없거나 로드되지 않았습니다. cp .env.example .env에서 존재하는지 확인하고 MCP 클라이언트의 env 블록 또는 npm run dev/npm start가 이를 읽고 있는지 확인하세요.

• 서버가 시작 시 잘못된 데이터베이스/사용자를 기록함 — DATABASE_URL을 확인하세요. 시작 로그(connected as "..." to database "...")는 쿼리가 실행되기 전에 이를 쉽게 잡을 수 있도록 특별히 출력됩니다.

• "Query rejected: ..." — 쿼리가 단일 SELECT/WITH 문이 아니거나 허용되지 않은 키워드를 포함했습니다. 이는 안전 모델의 계층 2가 의도대로 작동하는 것이지 버그가 아닙니다.

• 쿼리가 멈춘 후 오류 발생 — STATEMENT_TIMEOUT_MS에 도달했을 가능성이 높습니다. 워크로드가 정당하게 더 오래 필요하다면 .env에서 값을 높이거나 쿼리를 최적화하세요.

기여

이슈와 PR은 환영합니다. 이 도구는 의도적으로 작고 감사 가능한 도구입니다 — 목표는 안전 모델을 전체적으로 읽을 수 있을 만큼 단순하게 유지하는 것이지, 일반 쿼리 빌더로 성장시키는 것이 아닙니다.

라이선스

MIT