mcp-postgresdb-readonly

mcp-postgresdb-readonly

Serveur MCP pour accès PostgreSQL en lecture seule. Expose des outils d'exploration et de requêtage à tout client compatible MCP (Claude Code, Cursor, OpenCode, etc.).

Les opérations d'écriture sont bloquées au niveau applicatif, indépendamment des droits de l'utilisateur de la base de données.

Deux modes de fonctionnement :

• stdio : utilisé localement, l'agent IA lance le process directement.
• HTTP : hébergé sur un serveur, les agents s'y connectent via une URL.

Supporte jusqu'à trois environnements : staging, test, prod. Seuls ceux avec un HOST configuré sont chargés.

---

Outils MCP

| Outil | Description | |---|---| | query | Exécute une requête SELECT (écritures rejetées) | | list-tables | Liste les tables d'un schéma (ou de tous les schémas si aucun schéma par défaut n'est configuré) | | describe-table | Affiche colonnes, types, nullabilité, valeurs par défaut (tous les schémas si aucun par défaut) | | list-schemas | Liste tous les schémas définis par l'utilisateur | | list-environments | Liste les environnements configurés (sans credentials) |

---

Mode stdio (usage local)

Dans ce mode, chaque développeur installe le serveur sur sa propre machine. Le client IA (Claude Code, Cursor…) démarre automatiquement le serveur au moment où il en a besoin, et s'y connecte directement — pas de réseau, pas d'URL, pas de token.

Chaque développeur a ses propres credentials DB dans son .env local.

Prérequis : Node.js 18+ installé sur la machine.

1. Installer et builder

npm install
npm run build

2. Configurer

cp .env.dist .env

Renseigner dans .env au minimum un environnement :

POSTGRES_PROD_HOST=your-cluster.rds.amazonaws.com
POSTGRES_PROD_DATABASE=mydb
POSTGRES_PROD_USER=reader
POSTGRES_PROD_PASSWORD=secret

.env est git-ignoré et ne doit jamais être commité.

3. Déclarer le serveur dans le client IA

Le client IA a besoin du chemin absolu vers le fichier compilé. Récupérer ce chemin :

pwd
# exemple : /Users/alice/dev/mcp-postgresdb-readonly
# le fichier à déclarer : /Users/alice/dev/mcp-postgresdb-readonly/dist/index.js

Claude Code : ~/.claude/settings.json :

{
  "mcpServers": {
    "postgresdb-readonly": {
      "command": "node",
      "args": ["/chemin/absolu/vers/mcp-postgresdb-readonly/dist/index.js"]
    }
  }
}

Cursor : .cursor/mcp.json (projet) ou ~/.cursor/mcp.json (global) :

{
  "mcpServers": {
    "postgresdb-readonly": {
      "command": "node",
      "args": ["/chemin/absolu/vers/mcp-postgresdb-readonly/dist/index.js"]
    }
  }
}

Une fois configuré, redémarrer le client IA. Le serveur démarre automatiquement en arrière-plan à chaque session.

---

Mode HTTP (serveur hébergé)

Le serveur tourne sur une machine distante et expose un endpoint HTTPS. Les agents locaux s'y connectent via URL + Bearer token. Personne n'a besoin d'installer Node ou les credentials DB en local.

Architecture

Agents locaux (Claude, Cursor, OpenCode)
        │  HTTPS + Bearer token
        ▼
    nginx (SSL termination)
        │  HTTP loopback
        ▼
  Docker container  ←─── accès DB (prod/staging/test)
  (node dist/index.js, PORT=3000)

1. Prérequis serveur

• Un nom de domaine pointant vers le serveur (ex: mcp.example.com)
• Docker + Docker Compose
• Nginx
• Certbot (Let's Encrypt)
• make (optionnel, pour les commandes de gestion)

Installation sur Ubuntu/Debian :

# Docker
curl -fsSL https://get.docker.com | sh

# Nginx + Certbot
apt install -y nginx certbot python3-certbot-nginx make

# Démarrer et activer nginx
systemctl start nginx && systemctl enable nginx

2. Cloner le repo sur le serveur

git clone <repo-url> /opt/mcp-postgresdb-readonly
cd /opt/mcp-postgresdb-readonly

3. Configurer .env

cp .env.dist .env

Renseigner les credentials de base de données et impérativement générer un token d'auth :

# Générer un token sécurisé
openssl rand -hex 32

Exemple de .env :

# Token d'auth (obligatoire en mode HTTP)
MCP_AUTH_TOKEN=votre-token-généré-ici

# Connexion prod
POSTGRES_PROD_HOST=your-cluster.rds.amazonaws.com
POSTGRES_PROD_PORT=5432
POSTGRES_PROD_DATABASE=mydb
POSTGRES_PROD_USER=reader
POSTGRES_PROD_PASSWORD=secret
# POSTGRES_PROD_SCHEMA=myschema  # optional: restrict to a single schema; omit to access all schemas
POSTGRES_PROD_SSL=true

# Protections (optionnel, valeurs par défaut)
RATE_LIMIT_PER_MINUTE=60
QUERY_TIMEOUT_MS=30000
MAX_ROWS=1000

PORT ne doit pas être dans .env pour le mode Docker, il est imposé à 3000 par docker-compose.yml.

4. Lancer le container

docker compose up -d --build

Vérifier que le container est en bonne santé :

docker compose ps
docker compose logs -f
curl http://localhost:3000/health

La réponse attendue :

{"status":"ok","version":"2.0.0","environments":["prod"],"transport":"streamable-http"}

5. Obtenir un certificat SSL

La config nginx fournie référence les certificats Let's Encrypt. Il faut les obtenir avant d'activer cette config.

Laisser nginx tourner avec sa config par défaut (port 80), puis :

certbot certonly --nginx -d votre-domaine.com

certonly récupère uniquement le certificat sans modifier nginx.

6. Configurer nginx

Les certs existent maintenant, nginx -t passera :

DOMAIN=votre-domaine.com make nginx-setup

Ou manuellement :

cp .docker/nginx.conf /etc/nginx/sites-available/mcp-postgresdb
sed -i 's/mcp.example.com/votre-domaine.com/g' /etc/nginx/sites-available/mcp-postgresdb
ln -sf /etc/nginx/sites-available/mcp-postgresdb /etc/nginx/sites-enabled/mcp-postgresdb
nginx -t && systemctl reload nginx

7. Tester le endpoint

Vérifier que le token est bien exigé :

curl -s -o /dev/null -w "%{http_code}" -X POST https://votre-domaine.com/mcp
# doit retourner 401

Lister les outils disponibles (valide le token + la connexion MCP) :

curl -s -X POST https://votre-domaine.com/mcp \
  -H "Authorization: Bearer votre-token-généré-ici" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

8. Mettre à jour

make deploy

Ou manuellement :

git pull
docker compose up -d --build

---

Configurer les agents en mode HTTP

Une fois le serveur en ligne, partager le token aux PMs et développeurs. Chacun ajoute la config suivante dans son agent.

Claude Code

~/.claude/settings.json :

{
  "mcpServers": {
    "postgresdb-readonly": {
      "type": "http",
      "url": "https://votre-domaine.com/mcp",
      "headers": {
        "Authorization": "Bearer votre-token"
      }
    }
  }
}

Cursor

.cursor/mcp.json (projet) ou ~/.cursor/mcp.json (global) :

{
  "mcpServers": {
    "postgresdb-readonly": {
      "url": "https://votre-domaine.com/mcp",
      "headers": {
        "Authorization": "Bearer votre-token"
      }
    }
  }
}

OpenCode

~/.config/opencode/config.json :

{
  "mcp": {
    "postgresdb-readonly": {
      "type": "remote",
      "url": "https://votre-domaine.com/mcp",
      "headers": {
        "Authorization": "Bearer votre-token"
      }
    }
  }
}

---

Makefile

Le Makefile regroupe les commandes courantes pour la gestion du serveur.

| Commande | Description | |---|---| | make deploy | git pull + rebuild + redémarrage du container | | make restart | Redémarre le container sans rebuild | | make stop | Arrête le container | | make logs | Affiche les logs en temps réel | | make ps | État du container | | make health | Vérifie que le serveur répond sur localhost:3000 | | make token | Génère un nouveau Bearer token | | DOMAIN=... make nginx-setup | Installe et active la config nginx | | DOMAIN=... make ssl | Obtient un certificat SSL via Certbot |

---

Troubleshooting

Le container ne démarre pas

make logs
# ou
docker compose logs

Port 3000 déjà utilisé

ss -tlnp | grep 3000

La config nginx est invalide

nginx -t

Renouvellement SSL

Certbot configure un timer systemd automatique. Pour forcer le renouvellement :

certbot renew --dry-run

Vérifier que le container est en bonne santé

make ps
make health

---

Variables d'environnement

Connexions base de données

Chaque environnement utilise le préfixe POSTGRES_{ENV}_ où {ENV} vaut STAGING, TEST ou PROD. Si POSTGRES_{ENV}_HOST est absent, l'environnement est ignoré.

| Variable | Obligatoire | Défaut | Description | |---|---|---|---| | POSTGRES_{ENV}_HOST | oui | - | Hostname PostgreSQL | | POSTGRES_{ENV}_PORT | non | 5432 | Port TCP | | POSTGRES_{ENV}_DATABASE | oui | - | Nom de la base | | POSTGRES_{ENV}_USER | oui | - | Utilisateur | | POSTGRES_{ENV}_PASSWORD | oui | - | Mot de passe | | POSTGRES_{ENV}_SCHEMA | non | aucun (tous les schémas) | Restreint list-tables et describe-table à un schéma précis. Si absent, tous les schémas utilisateur sont accessibles. | | POSTGRES_{ENV}_SSL | non | true | false pour désactiver SSL (local/dev uniquement) |

Serveur HTTP

| Variable | Obligatoire | Défaut | Description | |---|---|---|---| | PORT | non | - | Si défini, démarre en mode HTTP sur ce port. Absent = mode stdio. | | MCP_AUTH_TOKEN | recommandé | - | Bearer token requis dans l'en-tête Authorization. Absent = serveur non protégé. |

Protections

| Variable | Défaut | Description | |---|---|---| | RATE_LIMIT_PER_MINUTE | 60 | Nombre max de requêtes par minute (fenêtre glissante globale) | | QUERY_TIMEOUT_MS | 30000 | Timeout PostgreSQL côté serveur (ms). La requête est annulée si dépassé. | | MAX_ROWS | 1000 | Si aucun LIMIT dans la requête, un LIMIT {MAX_ROWS} est injecté automatiquement. |

---

Protections

Trois mécanismes protègent la base contre les requêtes abusives (boucles IA, hallucinations) :

• Rate limiter : fenêtre glissante d'une minute. Au-delà de RATE_LIMIT_PER_MINUTE, les requêtes sont rejetées.
• Statement timeout : durée max d'exécution côté PostgreSQL. La requête est annulée automatiquement si dépassée.
• Auto LIMIT : si aucun LIMIT n'est présent, LIMIT {MAX_ROWS} est injecté. Évite les scans complets accidentels.
• Blocage écriture : les mots-clés INSERT, UPDATE, DELETE, DROP, TRUNCATE, ALTER, CREATE, REPLACE, GRANT, REVOKE, MERGE, UPSERT, VACUUM, REINDEX, COPY, DO, CALL sont rejetés avant que la requête n'atteigne la base. Les commentaires SQL en tête de requête (--, / /) sont strippés avant détection. EXPLAIN ANALYZE <write> est également bloqué (PostgreSQL exécute réellement la requête avec ANALYZE).

---

Logs

Chaque requête est loggée sur stderr :

[HH:MM:SS] ENV  outil | clé=valeur | ...

Exemples :

[11:52:26] PROD  query          | duration=257ms | rows=3    | sql=SELECT id, mail FROM users.user LIMIT 3
[11:52:26] STAGING  list-tables    | schema=all     | duration=300ms | tables=212
[11:52:26] STAGING  list-tables    | schema=public  | duration=300ms | tables=94
[11:52:26] TEST     describe-table | schema=all     | table=orders   | duration=247ms | columns=32
[11:52:26] PROD     query          | duration=12ms  | rows=1000 | limit=auto:1000 | sql=SELECT * FROM public.orders
[11:52:26] STAGING  query          | status=BLOCKED (write) | sql=INSERT INTO ...
[11:52:26] PROD  query          | status=RATE LIMITED | limit=60/min

PROD s'affiche en rouge, STAGING en jaune, TEST en cyan (si stderr est un TTY).

---

Sécurité

• Utiliser un utilisateur PostgreSQL dédié en lecture seule. Ne jamais utiliser owner ou un superutilisateur.
• En mode HTTP, toujours configurer MCP_AUTH_TOKEN. Générer un token par openssl rand -hex 32.
• .env est dans .gitignore et ne doit jamais être commité.
• En production, nginx est le seul point d'entrée public. Le container écoute uniquement sur 127.0.0.1:3000.