Tutorial MCP Server Python: Integrasi PostgreSQL ke Claude

Model Context Protocol (MCP) adalah standar terbuka yang diperkenalkan Anthropic untuk menghubungkan assistant AI dengan external data sources dan tools. Bayangkan MCP sebagai USB-C untuk AI: sebuah konektor universal yang memungkinkan model bahasa besar seperti Claude mengakses database, API internal, atau filesystem lokal secara aman dan terstruktur. Artikel ini akan membimbingmu membangun MCP server sederhana dengan Python yang menghubungkan PostgreSQL ke Claude Desktop, langkah demi langkah.

MCP menyelesaikan masalah klasik integrasi AI: setiap vendor AI punya format tool calling yang berbeda, sehingga membangun integrasi untuk OpenAI tidak bisa langsung dipakai untuk Anthropic atau Google. Dengan MCP, kamu menulis integrasi sekali, dan semua client yang mendukung protokol ini bisa menggunakannya. Ini menghemat waktu engineering secara drastis, terutama untuk tim yang men-deploy AI agent di berbagai platform sekaligus.

Persiapan Lingkungan Development

Sebelum mulai coding, pastikan sistemmu memiliki komponen berikut:

Python 3.10 atau lebih baru yang sudah terinstall.
PostgreSQL server yang bisa diakses, baik secara lokal maupun remote.
Claude Desktop yang sudah terinstall untuk testing integrasi.
Package manager uv atau pip untuk mengelola dependency.

Kamu juga perlu memahami konsep dasar MCP: server mendefinisikan resource yang bisa diakses client, tool yang bisa dipanggil, dan prompt template yang tersedia. Client kemudian menemukan kemampuan ini melalui discovery mechanism dan memutuskan kapan harus memanggilnya berdasarkan konteks percakapan.

Langkah 1: Instal SDK MCP untuk Python

Anthropic menyediakan SDK resmi untuk membangun MCP server dalam berbagai bahasa, termasuk Python. Buat virtual environment baru dan instal package yang diperlukan:

uv init mcp-postgres-server
cd mcp-postgres-server
uv add mcp psycopg2-binary

Package mcp berisi library server dan client, sementara psycopg2-binary adalah driver PostgreSQL untuk Python. Struktur project yang direkomendasikan terdiri dari satu file utama server.py dan file konfigurasi claude_desktop_config.json untuk mendaftarkan server ke Claude Desktop.

Langkah 2: Implementasi Resource untuk Daftar Tabel

Buat file server.py dan mulai dengan mengimpor modul yang diperlukan:

from mcp.server import Server
from mcp.types import Resource, Tool
import psycopg2
import json

server = Server("postgres-explorer")

@server.list_resources()
async def list_resources() -> list[Resource]:
    conn = psycopg2.connect("dbname=mydb user=postgres")
    cur = conn.cursor()
    cur.execute("SELECT table_name FROM information_schema.tables WHERE table_schema='public'")
    tables = cur.fetchall()
    cur.close(); conn.close()
    return [Resource(uri=f"postgres://{t[0]}", name=t[0]) for t in tables]

Decorator @server.list_resources() memberi tahu client bahwa server ini menyediakan resource yang bisa di-listing. Claude Desktop akan menampilkan daftar tabel ini sebagai referensi saat user bertanya tentang schema database.

Langkah 3: Implementasi Tool untuk Query Execution

Resource hanya memberi informasi metadata. Untuk memungkinkan Claude menjalankan query, kita perlu mendefinisikan tool:

@server.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="query_postgres",
            description="Jalankan SELECT query read-only di PostgreSQL",
            inputSchema={
                "type": "object",
                "properties": {
                    "sql": {"type": "string", "description": "Query SQL yang valid"}
                },
                "required": ["sql"]
            }
        )
    ]

@server.call_tool()
async def call_tool(name: str, arguments: dict) -> list:
    if name != "query_postgres":
        raise ValueError("Tool tidak dikenal")
    conn = psycopg2.connect("dbname=mydb user=postgres")
    cur = conn.cursor()
    cur.execute(arguments["sql"])
    rows = cur.fetchall()
    colnames = [desc[0] for desc in cur.description]
    cur.close(); conn.close()
    return [{col: val for col, val in zip(colnames, row)} for row in rows]

Tool schema menggunakan JSON Schema untuk mendeskripsikan parameter yang dibutuhkan. Claude akan menggunakan deskripsi ini untuk memutuskan kapan harus memanggil tool dan bagaimana membentuk argumen yang benar. Pastikan tool-mu read-only jika kamu tidak ingin model secara tidak sengaja mengubah data.

Langkah 4: Jalankan Server dan Daftarkan ke Claude Desktop

Tambahkan block berikut di akhir server.py untuk menjalankan server melalui stdio transport:

if __name__ == "__main__":
    from mcp.server.stdio import stdio_server
    import asyncio
    async def main():
        async with stdio_server() as (read_stream, write_stream):
            await server.run(read_stream, write_stream)
    asyncio.run(main())

Kemudian buat atau edit file konfigurasi Claude Desktop. Di macOS, file ini berada di ~/Library/Application Support/Claude/claude_desktop_config.json. Tambahkan entry berikut:

{
  "mcpServers": {
    "postgres-explorer": {
      "command": "uv",
      "args": ["run", "python", "/path/to/mcp-postgres-server/server.py"]
    }
  }
}

Restart Claude Desktop setelah menyimpan konfigurasi. Seharusnya kamu akan melihat ikon palu (hammer) baru di sidebar yang menandakan tool PostgreSQL sudah tersedia.

Langkah 5: Uji Integrasi dengan Percakapan Natural

Buka jendela chat baru di Claude Desktop dan ajukan pertanyaan seperti:

Berapa total transaksi di tabel orders bulan lalu?

Claude seharusnya akan secara otomatis memanggil tool query_postgres dengan SQL yang sesuai, mengeksekusinya melalui server yang kamu bangun, lalu menyajikan hasilnya dalam bahasa natural. Jika query gagal, Claude biasanya akan mencoba lagi dengan query yang dikoreksi berdasarkan daftar resource yang tersedia.

Model tidak melihat data mentah kecuali melalui tool call. Semua akses database terjadi melalui boundary yang kamu kontrol, sehingga kamu bisa menambahkan audit log atau rate limiting di level tool.

Best Practice dan Tradeoff

Ketika membangun MCP server untuk production, pertimbangkan beberapa hal berikut:

Read-only default: Selalu mulai dengan akses read-only. Operasi write harus memiliki konfirmasi eksplisit dari user.
Connection pooling: Gunakan connection pool untuk menghindari overhead pembukaan koneksi baru pada setiap tool call.
Timeout: Tetapkan timeout query agar query kompleks tidak membuat Claude Desktop hang.
Logging: Catat setiap query yang dijalankan oleh tool untuk audit dan debugging.

MCP masih dalam tahap awal adopsi, tapi momentumnya tumbuh cepat. Selain Claude Desktop, IDE seperti Zed dan Cursor juga mulai menambahkan dukungan MCP untuk integrasi AI dengan codebase internal. Membangun server MCP hari ini adalah investasi yang akan semakin bernilai seiring bertambahnya client yang mendukung protokol ini.

Sumber referensi: Dokumentasi Resmi MCP, MCP Python SDK di GitHub

Tutorial Membangun MCP Server dengan Python: Hubungkan PostgreSQL ke Claude Desktop