Quarkus MCP Servers

Quarkus-based MCP servers for interacting with JDBC databases, filesystems, and Docker containers.

GitHub

Quarkus MCP Servers

Server MCP (Model Context Protocol) universali basati su Quarkus. Supporta database JDBC, filesystem, container Docker e molto altro con un singolo JAR.

🚀 Setup Rapido

1. Setup JDK 17

Il progetto richiede JDK 17. Usa lo script automatico per scaricarlo e configurarlo:

# Setup automatico JDK 17
./setup-jdk17.sh

Lo script:

  • Rileva automaticamente l'architettura (x64, aarch64) e OS (Linux, macOS)
  • Scarica JDK 17 da Eclipse Temurin
  • Configura le variabili d'ambiente JAVA_HOME e PATH
  • Crea un file di configurazione jdk17/jdk-env.sh per riutilizzi futuri

Dopo l'installazione, carica l'ambiente JDK:

source jdk17/jdk-env.sh

2. Compilazione

Una volta configurato JDK 17, compila il progetto:

# Compila tutti i moduli (senza test per velocità)
./build-no-tests.sh

Il comando creerà i JAR in:

  • jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar - Server JDBC
  • filesystem/target/mcp-server-filesystem-999-SNAPSHOT.jar - Server Filesystem
  • containers/target/mcp-server-containers-999-SNAPSHOT.jar - Server Container
  • jvminsight/target/mcp-server-jvminsight-999-SNAPSHOT.jar - Server JVM Insights

🐳 Utilizzo con Docker

Build immagine Docker

# Builda l'immagine Docker con tutti i server
./docker-mcp.sh build

Server JDBC

# Oracle (richiede Oracle su localhost:1521)
./docker-mcp.sh oracle

# Oracle in modalità read-only (solo lettura)
./docker-mcp.sh run jdbc --jdbc.url="jdbc:oracle:thin:@localhost:1521:xe" --jdbc.user="ORACLEUSR" --jdbc.password="ORACLEUSR" --jdbc.readonly=true

# H2 in memoria
./docker-mcp.sh h2

# Server JDBC generico
./docker-mcp.sh run jdbc --jdbc.url="jdbc:postgresql://localhost:5432/mydb" --jdbc.user="user" --jdbc.password="pass"

# MySQL in modalità read-only
./docker-mcp.sh run jdbc --jdbc.url="jdbc:mysql://localhost:3306/mydb" --jdbc.user="root" --jdbc.password="toor" --jdbc.readonly=true

# PostgreSQL in modalità read-only
./docker-mcp.sh run jdbc --jdbc.url="jdbc:postgresql://localhost:5432/mydb" --jdbc.user="postgres" --jdbc.password="postgres" --jdbc.readonly=true

# Server JDBC in modalità read-only
./docker-mcp.sh run jdbc --jdbc.url="jdbc:postgresql://localhost:5432/mydb" --jdbc.user="user" --jdbc.password="pass" --jdbc.readonly=true

Server Filesystem

# Monta /tmp come directory condivisa
./docker-mcp.sh filesystem /tmp

# Directory personalizzata
./docker-mcp.sh filesystem /path/to/directory

Altri server

# Container Docker
./docker-mcp.sh run containers

# JVM Insights
./docker-mcp.sh run jvminsight

⚙️ Configurazione MCP

Generazione automatica

Genera automaticamente la configurazione MCP per Claude Desktop:

./docker-mcp.sh config

Questo crea il file mcp-docker-config.json con configurazioni per:

  • Server JDBC Oracle
  • Server JDBC H2
  • Server Filesystem
  • Server Container
  • Server JVM Insights

Configurazione manuale per Claude Desktop

Linux/macOS

Copia il contenuto del file generato in:

~/.config/claude/claude_desktop_config.json

Windows

%APPDATA%/Claude/claude_desktop_config.json

Configurazione per Docker

Esempio configurazione Docker:

{
  "mcpServers": {
    "jdbc-oracle-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network", "host",
        "mcp-servers:latest", "jdbc",
        "--jdbc.url=jdbc:oracle:thin:@localhost:1521:xe",
        "--jdbc.user=ORACLEUSR",
        "--jdbc.password=ORACLEUSR",
        "--jdbc.readonly=false"
      ]
    },
    "jdbc-oracle-readonly": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "--network", "host",
        "mcp-servers:latest", "jdbc",
        "--jdbc.url=jdbc:oracle:thin:@localhost:1521:xe",
        "--jdbc.user=ORACLEUSR",
        "--jdbc.password=ORACLEUSR",
        "--jdbc.readonly=true"
      ]
    },
    "jdbc-h2-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "-p", "3000:3000",
        "mcp-servers:latest", "jdbc",
        "--jdbc.url=jdbc:h2:mem:testdb",
        "--jdbc.user=sa",
        "--jdbc.password=",
        "--jdbc.readonly=false"
      ]
    },
    "jdbc-mysql-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network",
        "host",
        "mcp-servers:latest",
        "jdbc",
        "--jdbc.url=jdbc:mysql://localhost:3306/mydb",
        "--jdbc.user=root",
        "--jdbc.password=toor",
        "--jdbc.readonly=true"
      ]
    },
    "jdbc-postgres-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--network",
        "host",
        "mcp-servers:latest",
        "jdbc",
        "--jdbc.url=jdbc:postgresql://localhost:5432/mydb",
        "--jdbc.user=postgres",
        "--jdbc.password=postgres",
        "--jdbc.readonly=true"
      ]
    },
    "filesystem-docker": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm", "-v", "/tmp:/mnt/shared",
        "mcp-servers:latest", "filesystem", "/mnt/shared"
      ]
    }
  }
}

Configurazione per Esecuzione Locale (senza Docker)

Quando esegui i server localmente senza Docker, usa questa configurazione:

{
  "mcp": {
    "servers": {
      "jdbc-oracle": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar",
          "--jdbc.url=jdbc:oracle:thin:@localhost:1521:xe",
          "--jdbc.user=ORACLEUSR",
          "--jdbc.password=ORACLEUSR",
          "--jdbc.readonly=false"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/jdbc"
      },
      "jdbc-oracle-readonly": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar",
          "--jdbc.url=jdbc:oracle:thin:@localhost:1521:xe",
          "--jdbc.user=ORACLEUSR",
          "--jdbc.password=ORACLEUSR",
          "--jdbc.readonly=true"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/jdbc"
      },
      "jdbc-h2": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar",
          "--jdbc.url=jdbc:h2:mem:testdb",
          "--jdbc.user=sa",
          "--jdbc.password=",
          "--jdbc.readonly=false"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/jdbc"
      },
      "jdbc-mysql": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar",
          "--jdbc.url=jdbc:mysql://localhost:3306/mydb",
          "--jdbc.user=root",
          "--jdbc.password=toor",
          "--jdbc.readonly=true"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/jdbc"
      },
      "jdbc-postgres": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar",
          "--jdbc.url=jdbc:postgresql://localhost:5432/mydb",
          "--jdbc.user=postgres",
          "--jdbc.password=postgres",
          "--jdbc.readonly=true"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/jdbc"
      },
      "filesystem-local": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/filesystem/target/mcp-server-filesystem-999-SNAPSHOT.jar",
          "/tmp"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/filesystem"
      },
      "containers-local": {
        "type": "stdio",
        "command": "/workspace/db-ready/quarkus-mcp-servers/jdk17/bin/java",
        "args": [
          "-jar",
          "/workspace/db-ready/quarkus-mcp-servers/containers/target/mcp-server-containers-999-SNAPSHOT.jar"
        ],
        "cwd": "/workspace/db-ready/quarkus-mcp-servers/containers"
      }
    }
  }
}

📋 Comandi Disponibili

setup-jdk17.sh

./setup-jdk17.sh              # Setup automatico JDK 17
./setup-jdk17.sh --help       # Mostra opzioni disponibili
./setup-jdk17.sh --force      # Forza reinstallazione anche se esiste

docker-mcp.sh

./docker-mcp.sh build         # Builda immagine Docker
./docker-mcp.sh oracle        # Server JDBC Oracle
./docker-mcp.sh h2            # Server JDBC H2
./docker-mcp.sh filesystem [path]  # Server Filesystem
./docker-mcp.sh config        # Genera configurazione MCP
./docker-mcp.sh help          # Mostra aiuto

🗄️ Database Supportati

Il server JDBC supporta tutti i database con driver JDBC:

  • Oracle - jdbc:oracle:thin:@host:port:sid
  • PostgreSQL - jdbc:postgresql://host:port/database
  • MySQL - jdbc:mysql://host:port/database
  • H2 - jdbc:h2:mem:testdb (in memoria) o jdbc:h2:file:/path/to/db
  • SQLite - jdbc:sqlite:/path/to/database.db
  • SQL Server - jdbc:sqlserver://host:port;databaseName=db
  • MariaDB - jdbc:mariadb://host:port/database

🔒 Modalità Read-Only per Server JDBC

Il server JDBC supporta una modalità read-only che permette di esplorare e interrogare i database senza rischio di modifiche accidentali.

Funzionalità in Modalità Read-Only

✅ Operazioni Permesse:

  • read_query - Esecuzione di query SELECT
  • list_tables - Visualizzazione tabelle
  • describe_table - Descrizione struttura tabelle
  • database_info - Informazioni database (include stato read-only)

❌ Operazioni Bloccate:

  • write_query - INSERT, UPDATE, DELETE
  • create_table - Creazione tabelle

Come Attivare la Modalità Read-Only

Docker:

./docker-mcp.sh run jdbc \
  --jdbc.url="jdbc:oracle:thin:@localhost:1521:xe" \
  --jdbc.user="ORACLEUSR" \
  --jdbc.password="ORACLEUSR" \
  --jdbc.readonly=true

Esecuzione Locale:

java -jar jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar \
  --jdbc.url="jdbc:h2:mem:testdb" \
  --jdbc.user="sa" \
  --jdbc.password="" \
  --jdbc.readonly=true

Verifica Stato Read-Only

Usa il tool database_info per verificare lo stato:

{
  "database_product_name": "Oracle",
  "mcp_server_readonly_mode": "true",
  "read_only": "false",
  ...
}

Nota: mcp_server_readonly_mode indica la modalità del server MCP, mentre read_only indica se il database stesso è in sola lettura.

🔧 Esecuzione Locale (senza Docker)

Server JDBC

source jdk17/jdk-env.sh

# Modalità standard (read/write)
java -jar jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar \
  --jdbc.url="jdbc:h2:mem:testdb" \
  --jdbc.user="sa" \
  --jdbc.password="" \
  --jdbc.readonly=false

# Modalità read-only (solo lettura)
java -jar jdbc/target/mcp-server-jdbc-universal-999-SNAPSHOT.jar \
  --jdbc.url="jdbc:h2:mem:testdb" \
  --jdbc.user="sa" \
  --jdbc.password="" \
  --jdbc.readonly=true

Server Filesystem

source jdk17/jdk-env.sh
java -jar filesystem/target/mcp-server-filesystem-999-SNAPSHOT.jar /tmp

🔍 Testing

Test server locale

# Test JDBC H2
./run-server.sh jdbc --jdbc.url="jdbc:h2:mem:testdb" --jdbc.user="sa"

# Test Filesystem
./run-server.sh filesystem /tmp

Test Docker

# Test setup Docker
./test-docker-setup.sh

📁 Struttura Progetto

quarkus-mcp-servers/
├── setup-jdk17.sh          # Setup automatico JDK 17
├── docker-mcp.sh           # Script Docker per MCP
├── build-no-tests.sh       # Build senza test
├── run-server.sh           # Esecuzione server locale
├── jdbc/                   # Server JDBC
├── filesystem/             # Server Filesystem  
├── containers/             # Server Container Docker
├── jvminsight/            # Server JVM Insights
├── jdk17/                 # JDK 17 (creato da setup)
├── mcp-configs/           # Configurazioni MCP
└── mcp-docker-config.json # Config generata per Docker

🚨 Troubleshooting

JDK 17 non trovato

# Reinstalla JDK 17
./setup-jdk17.sh --force

# Carica ambiente
source jdk17/jdk-env.sh

# Verifica versione
java -version

Docker image non trovata

# Rebuilda immagine
./docker-mcp.sh build

Errori di connessione database

  • Verifica che il database sia in esecuzione
  • Controlla URL, username e password
  • Per Oracle, assicurati che sia su localhost:1521

Problemi con Docker Desktop

# Su Linux, assicurati che Docker sia in esecuzione
sudo systemctl start docker

# Aggiungi utente al gruppo docker
sudo usermod -aG docker $USER
# Poi fai logout/login

📚 Documentazione Aggiuntiva

🤝 Contributi

  1. Fork del repository
  2. Crea feature branch (git checkout -b feature/amazing-feature)
  3. Commit dei cambiamenti (git commit -m 'Add amazing feature')
  4. Push al branch (git push origin feature/amazing-feature)
  5. Apri Pull Request

📝 Licenza

Questo progetto è sotto licenza MIT. Vedi il file LICENSE per dettagli.

Related Servers