🗄️ PostgreSQL용 MCP 서버 구축: Claude 및 모든 AI 클라이언트로 데이터베이스 쿼리하기 즐겁게 빌드하세요

Source: Dev.to

소개

Model Context Protocol (MCP)는 AI 애플리케이션이 데이터 소스와 상호 작용하는 방식을 혁신하고 있습니다. 날씨 서버와 기본 예제는 좋은 시작점이지만, 대부분의 실제 애플리케이션은 데이터베이스 접근이 필요합니다. 이 가이드에서는 Claude, VS Code 및 모든 MCP 클라이언트가 데이터베이스를 안전하고 효율적으로 쿼리할 수 있는 프로덕션 수준의 PostgreSQL MCP 서버를 구축합니다.

끝까지 진행하면 다음을 갖게 됩니다:

• 완전한 기능을 갖춘 PostgreSQL MCP 서버
• SELECT 쿼리, 집계 및 데이터 검색 예시
• 프로덕션에 배포할 수 있는 공개 저장소
• Claude Desktop 및 기타 MCP 클라이언트와의 통합

이것이 해결하는 문제는 무엇인가요?

Claude에게 다음과 같이 물어본다고 상상해 보세요:

“이번 분기 매출 기준 상위 10명의 고객은 누구인가요?”

또는:

“지난 7일 동안 심각도 ‘critical’인 모든 인시던트를 보여 주세요.”

PostgreSQL MCP 서버를 사용하면 Claude는:

• 데이터베이스에 직접 연결
• 안전하고 사전 정의된 쿼리 실행
• 구조화된 데이터 반환
• 실시간으로 데이터를 분석하고 조치를 취하도록 도움

이는 다음에 적합합니다:

• AI 기반 BI 대시보드
• 인시던트 관리 자동화
• 고객 데이터 분석
• 실시간 보고 및 인사이트

아키텍처 개요

Our MCP Server acts as a bridge between MCP clients (Claude, VS Code) and PostgreSQL:

MCP Client (Claude)
       |
    MCP Protocol
       |
    MCP Server (TypeScript)
       |
  pg (PostgreSQL Driver)
       |
  PostgreSQL Database

사전 요구 사항

• Node.js 18 이상
• TypeScript 지식
• PostgreSQL 데이터베이스
• 기본 MCP 이해

단계 1: 프로젝트 설정

Create the project:

mkdir mcp-postgres-server
cd mcp-postgres-server
npm init -y
npm install @modelcontextprotocol/sdk pg dotenv
npm install -D typescript @types/node @types/pg

Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "node",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true
  }
}

단계 2: 데이터베이스 서비스

Create src/database.ts:

import { Pool } from 'pg';
import dotenv from 'dotenv';

dotenv.config();

const pool = new Pool({
  connectionString: process.env.DATABASE_URL,
});

export class DatabaseService {
  async queryUsers(): Promise {
    const result = await pool.query(
      'SELECT id, name, email FROM users LIMIT 10'
    );
    return result.rows;
  }

  async queryIncidents(status: string): Promise {
    const result = await pool.query(
      'SELECT id, title, status, severity FROM incidents WHERE status = $1 ORDER BY created_at DESC',
      [status]
    );
    return result.rows;
  }

  async getStats(): Promise {
    const result = await pool.query(`
      SELECT 
        COUNT(*) as total_incidents,
        SUM(CASE WHEN severity = 'critical' THEN 1 ELSE 0 END) as critical_count,
        SUM(CASE WHEN status = 'open' THEN 1 ELSE 0 END) as open_count
      FROM incidents
    `);
    return result.rows[0];
  }
}

단계 3: MCP 서버 구현

Create src/server.ts:

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
import { DatabaseService } from './database.js';

const server = new Server({
  name: 'postgres-mcp-server',
  version: '1.0.0',
});

const db = new DatabaseService();

server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    {
      name: 'get_users',
      description: 'Retrieve recent users from the database',
      inputSchema: {
        type: 'object',
        properties: {},
        required: [],
      },
    },
    {
      name: 'get_open_incidents',
      description: 'Get all open incidents sorted by date',
      inputSchema: {
        type: 'object',
        properties: {},
        required: [],
      },
    },
    {
      name: 'get_database_stats',
      description: 'Get incident statistics (total, critical, open)',
      inputSchema: {
        type: 'object',
        properties: {},
        required: [],
      },
    },
  ],
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  const { name } = request.params;

  try {
    if (name === 'get_users') {
      const users = await db.queryUsers();
      return {
        content: [{ type: 'text', text: JSON.stringify(users, null, 2) }],
      };
    }

    if (name === 'get_open_incidents') {
      const incidents = await db.queryIncidents('open');
      return {
        content: [{ type: 'text', text: JSON.stringify(incidents, null, 2) }],
      };
    }

    if (name === 'get_database_stats') {
      const stats = await db.getStats();
      return {
        content: [{ type: 'text', text: JSON.stringify(stats, null, 2) }],
      };
    }

    return {
      content: [{ type: 'text', text: `Unknown tool: ${name}` }],
      isError: true,
    };
  } catch (error) {
    return {
      content: [
        {
          type: 'text',
          text: `Error: ${error instanceof Error ? error.message : String(error)}`,
        },
      ],
      isError: true,
    };
  }
});

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error('PostgreSQL MCP Server running on stdio');
}

main().catch(console.error);

단계 4: 설정

Create .env:

DATABASE_URL=postgresql://user:password@localhost:5432/mydb

Update package.json scripts:

{
  "scripts": {
    "build": "tsc",
    "start": "node dist/server.js",
    "dev": "tsc && npm start"
  },
  "type": "module"
}

단계 5: 로컬에서 실행

npm run build
npm start

단계 6: Claude Desktop 연결

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\\Claude\\claude_desktop_config.json

{
  "mcpServers": {
    "postgres": {
      "command": "node",
      "args": ["/absolute/path/to/dist/server.js"],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/mydb"
      }
    }
  }
}

Claude Desktop을 재시작하세요. 이제 데이터베이스 아이콘이 표시되고 이 도구들에 접근할 수 있습니다!

프로덕션을 위한 모범 사례

• 연결 풀링: pg Pool 사용 (이미 코드에 포함됨)
• 파라미터화된 쿼리: 항상 $1, $2 자리표시자 사용
• 오류 처리: 의미 있는 오류를 포착하고 반환
• 검증: 쿼리 전에 도구 입력 검증
• 모니터링: 모든 쿼리와 응답 시간을 기록
• 속도 제한: 대량 요청에 대한 백프레셔 구현

공개 저장소

전체 소스 코드는 다음에서 확인할 수 있습니다:
GitHub Repository: mcp‑postgres‑server

저장소에는 다음이 포함됩니다:

• 전체 TypeScript 구현
• Docker 지원
• 배포 스크립트
• 예시 스키마
• 통합 테스트

배포 옵션

Google Cloud Run

gcloud run deploy mcp-postgres \
  --source . \
  --set-env-vars DATABASE_URL=your_connection_string

로컬 Docker

docker build -t mcp-postgres .
docker run -e DATABA