postgres-mcp

Postgres – 어느 Postgres 데이터베이스든 읽기 전용으로 조회할 수 있는 범용·재사용 가능한 MCP 서버입니다. 특정 스키마에 대한 지식이 없으며, list_tables, describe_table, run_sql은 오직 information_schema와 범용 json introspection만으로 동작하므로 코드 변경 없이Postgres 데이터베이스에 연결할 수 있습니다.

보안 모델

두 개의 독립된 레이어로 심층 방어를 제공합니다:

1. DB 레벨: 서버는 SELECT 권한만 부여된 롤로 연결되며, 쿼리가 시도해도 쓰기는 불가능합니다. setup_reader_role.sql을 사용해 이 역할을 생성하세요.

2. 앱 레벨: run_sql()은 단순 SELECT(또는 WITH ... SELECT)만 허용하며 그 외에는 전부 거부합니다. 또한 200행 상한을 적용하고, 5초 문장 타임아웃을 설정합니다. 이 모든 것은 데이터베이스에 실제로 닿기도 전에 즉시 실패시키는 fast-fail 검사로 실행됩니다.

Related MCP server: pg-mcp

설정

1. 대상 데이터베이스에 읽기 전용 역할을 만듭니다.

   • setup_reader_role.sql을 열어 비밀번호 자리표시자와 <your_db_name>을 실제 값으로 교체한 뒤, 데이터베이스에 대해 한 번 실행합니다(예: psql 또는 DB 공급자의 SQL 콘솔).

2. 이 디렉터리의 .env 파일에 연결 문자열을 설정합니다:

   DATABASE_URL=postgresql://mcp_reader:yourpassword@host:5432/yourdb
   ANTHROPIC_API_KEY=sk-ant-...

   (ANTHROPIC_API_KEY는 chat.py 실행에만 필요하며, MCP 서버 자체 실행에는 필요없습니다.)

3. 의존성을 설치합니다:

   pip install -r requirements.txt

로컬 테스트

먼저 MCP 클라이언트를 통하지 않고 쿼리 계층을 직접 테스트합니다:

python chat.py "what tables do I have?"

그런 다음 Inspector에서 실제 MCP 서버로 테스트합니다:

fastmcp dev inspector mcp_server.py

Inspector의 Node 툴체인이 문제를 일으키면(이전에도 그런 사례가 있었습니다), 서버를HTTP 위에서 직접 실행하고 FastMCP Python 클라이언트로 요청을 보내는 방식으로 대체합니다:

fastmcp run mcp_server.py --transport http --port 8000

from fastmcp import Client
import asyncio

async def main():
    async with Client("http://localhost:8000/mcp") as client:
        print(await client.call_tool("list_tables", {}))

asyncio.run(main())

배포 (Prefect Horizon)

FastMCP의 호스트 배포 플랫폼은 현재 Prefect Horizon입니다(이전에는 “FastMCP Cloud”였으며, 브랜드가 바뀐 적이 여러 번 있으므로 이 단계를 따르기 전에 gofastmcp.com/deployment에서 현재 이름/URL을 다시 확인하세요).

1. 저장소를 GitHub에 푸시합니다 — 실제 원격 저장소(remote)가 반드시 먼저 존재해야 합니다 (아직 없다면 README 맨 아래 git 기증절을 설명).

2. 현재 플랫폼 사이트(작성 시점: horizon.prefect.io)로 이동하여 GitHub로 로그인합니다.

3. 이 저장소를 연결설정합니다.

4. 배포를 규정합니다.

   • Entrypoint: mcp_server.py:mcp — 여기서 :mcp는 파일 안에서 서버 객체가 할당된 변수 이름입니다(mcp_server.py에 있는 mcp = FastMCP(...) 줄 참조). 안 되는 시 변수 이름을 바꿀 경우 이 진입점 문자열도 정확히 일치하도록 수정해야 합니다.

   • 인증: ON으로 켜 둡니다. claude.ai나 Claude Desktop 같은 대화형 MCP 클라이언트는 연결하려면 실제 OAuth 디스커버리 엔드포인트를 필요로 합니다. 인증이 활성화되지 않은 서버는 원시 API 호출이나FastMCP Python 클라이언트로 직접 테스트할 때는 정상 작동할지언정 해당 클라이언트와는 작동하지 않습니다.

   • Environment variables: 플랫폼의 자체 대시보드에서 DATABASE_URL을 추가합니다. 이것은 이 프로젝트의 로컬 .env 파일과는 다른 것입니다며 그 파일을 읽지 않습니다 — 대시보드에 직접 값을 입력해야 배포된 서버가 DB에 접근할 수 있습니다.

5. 배포하고 결과 서버 URL을 복사합니다. https://<your-server-name>.fastmcp.app/mcp 형태일 것입니다(정확한 도메인은 다를 수 있으므로 항상 플랫폼에 실제로 표시된 것을 사용하세요).

6. 다른 곳에 연결하기 전에 먼저 플랫폼 자체의 내장 Inspector/테스트 도구로 검증합니다. 거기서 list_tables를 먼저 호출합니다— 인자가 없어서 배포된 서버가 실제로 DB에 connect할 수 있는지 가장 빠르게 확인할 수 있습니다.

claude.ai에 연결하기

1. claude.ai → Settings → Connectors → Add custom connector 로 이동합니다.

2. 위 배포 단계의 서버 URL을 붙여넣습니다.

3. 안내에 따라 OAuth 프롬프트를 완료합니다.

4. 커넥터 추가 이전이 아닌 새 채팅을 시작한 후, 해당 채팅에서 커넥터를 활성화합니다.

5. “what tables do I have?”와 같은 간단한 질문으로 테스트합니다.

6. 나중에 새 도구를 추가해도 표시되지 않으면, 뭔가가 고장났다고 생각하기 전에 커넥터 설정에서 “Refresh tools”를 먼저 시도하세요. 이는 알려진 캐싱 동작일 뿐, 버그가 아닙니다.

제한 사항

이것은 정말로 스키마-agnostic 하지만제약이 없는 것은 아니며:

• Postgres 전용입니다. jsonb_object_keys()와 Postgres 카탈로그 문법(information_schema 등)을 사용합니다. MySQL이나 SQLite에 연결하려면 db_toolkit 파일을 실제 코딩 변경해야 하지, 연결 문자열만 바로 갈아 끼울 수는 없습니다.

• 스키마-agnostic ≠ DB별 작업이 없다. 각 새 대상 데이터베이스에는 여전히 자체 읽기 역할(setup_reader_role.sql)을 생성하고, 별도 배포(또는 최소한 별도 DATABASE_URL)를 만들어야 합니다. 이것은 여러 DB를 한 개체 서버가 투명하게 제공하는 방식이 아닙니다.

Git 설정

아직 git 히스토리가 없는 이 코드에서 시작했다면:

git init
git add .
git commit -m "Initial commit: generic read-only Postgres MCP server"
git branch -M main
git remote add origin <your-repo-url>
git push -u origin main