Which integrations are available for this server?

Allows executing SQL queries against MySQL databases with configurable permissions, automatic LIMIT, and audit logging. Allows executing SQL queries against PostgreSQL databases with configurable permissions, automatic LIMIT, and audit logging. Allows executing SQL queries against SQLite databases with configurable permissions and audit logging.

How do I use mcp-query?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-query list tables from local-mysql" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

mcp-query

by ottimis

Overview Schema Source Related Servers Discussions Admin

Python

Local

MCP Query

MCP server locale per eseguire query database da Claude Code in modo sicuro. Le credenziali sono nel Portachiavi Apple, ogni connessione ha un livello di permessi che controlla quali operazioni sono consentite, e tutte le query vengono loggate per audit.

MCP Query - Web UI

Requisiti

Python >= 3.10
uv (package manager)
macOS (per il Portachiavi Apple)

Related MCP server: imessage-mcp

Installazione

# Clona o entra nella directory del progetto
cd mcp-query

# Installa dipendenze
uv sync

Setup

1. Configura le connessioni

Copia il file di esempio e personalizzalo:

cp config.example.yaml ~/.mcp-query/config.yaml

Modifica ~/.mcp-query/config.yaml:

defaults:
  max_rows: 500           # Limite righe per SELECT
  permissions: read       # Permesso default
  log_retention_days: 30  # Retention log in giorni

connections:
  local-mysql:
    driver: mysql           # mysql | pgsql | sqlite
    host: localhost
    port: 3306
    database: myapp
    user: root
    permissions: write      # preset: select + insert/update/delete
    max_rows: 1000

  staging-api:
    driver: mysql
    host: staging-db.example.com
    port: 3306
    database: api
    user: developer
    permissions: [select, insert]  # granulare: solo queste operazioni

  prod-db:
    driver: pgsql
    host: db.example.com
    port: 5432
    database: analytics
    user: readonly_user
    permissions: read       # preset: solo select

  local-sqlite:
    driver: sqlite
    database: /path/to/database.sqlite
    permissions: admin      # preset: tutte le operazioni

2. Imposta le password

Le password vengono salvate nel Portachiavi Apple, mai su file.

Da terminale:

uv run mcp-query set-password local-mysql
# Ti chiede la password in modo interattivo

Dalla Web UI:

uv run mcp-query ui
# Si apre http://localhost:9847 nel browser

Dalla UI puoi aggiungere connessioni, impostare password, testare la connettivita' e consultare i log.

3. Registra in Claude Code

# Globale (disponibile in tutti i progetti)
claude mcp add --scope user db -- \
  uv run --directory /path/to/mcp-query mcp-query serve

# Solo nel progetto corrente
claude mcp add db -- \
  uv run --directory /path/to/mcp-query mcp-query serve

Sostituisci /path/to/mcp-query con il path reale del progetto. Da quel momento Claude Code avra' accesso ai tools database.

Per indicare a Claude quale connessione usare automaticamente in un progetto, aggiungi nel CLAUDE.md del progetto:

## Database
Per le query al database usare il tool MCP `query` con connessione `nome-connessione`.

Comandi CLI

Comando	Descrizione
`mcp-query serve`	Avvia il server MCP (usato da Claude Code via stdio)
`mcp-query ui`	Apre la Web UI di gestione nel browser
`mcp-query list`	Mostra le connessioni configurate
`mcp-query set-password <nome>`	Salva la password nel Portachiavi
`mcp-query logs`	Mostra le ultime query dal log
`mcp-query logs -c <nome> -n 50`	Filtra per connessione, ultime 50

Tools MCP

Questi sono i tools che Claude Code puo' chiamare:

`list_connections`

Mostra tutte le connessioni configurate con driver, database e livello permessi.

`list_tables`

connection: "local-mysql"

Lista le tabelle del database.

`describe_table`

connection: "local-mysql"
table: "users"

Mostra la struttura della tabella (colonne, tipi, chiavi).

`query`

connection: "local-mysql"
sql: "SELECT * FROM users WHERE active = 1"

Esegue una query SQL. Il tipo di query viene rilevato automaticamente e confrontato con i permessi della connessione. Se il permesso e' insufficiente, la query viene bloccata.

`query_log`

connection: ""     # vuoto = tutte
limit: 20

Mostra le ultime query eseguite dal log di audit.

Permessi

I permessi si configurano in due modi:

Preset (shorthand)

Preset	Operazioni consentite
`read`	select, show, describe, explain
`write`	read + insert, update, delete
`admin`	write + create, alter, drop, truncate, grant, revoke

permissions: read

Granulare (lista esplicita)

Puoi specificare esattamente quali operazioni sono consentite:

# Solo SELECT e INSERT, niente UPDATE/DELETE
permissions: [select, insert]

# SELECT con possibilita' di creare tabelle
permissions: [select, describe, create]

# Tutto tranne DROP
permissions: [select, show, describe, explain, insert, update, delete, create, alter]

Operazioni disponibili: select, show, describe, explain, insert, update, delete, replace, create, alter, drop, truncate, grant, revoke, rename.

La Web UI fornisce checkbox raggruppati per categoria (Read/Write/DDL) con preset rapidi.

Protezioni

Multi-statement bloccati: query con piu' di un ; vengono rifiutate
LIMIT automatico: i SELECT senza LIMIT ricevono automaticamente il max_rows della connessione
Query sconosciute bloccate: solo i tipi di statement esplicitamente mappati sono consentiti

Audit Log

Ogni query eseguita (incluse quelle bloccate) viene salvata in ~/.mcp-query/logs/queries-YYYY-MM-DD.jsonl.

Formato di ogni riga:

{
  "ts": "2026-03-31T14:22:05.123456+00:00",
  "connection": "local-mysql",
  "sql": "SELECT * FROM users WHERE id = 1",
  "query_type": "SELECT",
  "permission": "read",
  "status": "ok",
  "rows_affected": 1,
  "execution_ms": 12.5,
  "error": null
}

I valori di status sono:

ok - query eseguita con successo
denied - bloccata dai permessi
error - errore durante l'esecuzione

I log vengono cancellati automaticamente dopo log_retention_days giorni (default: 30).

Web UI

uv run mcp-query ui

Apre http://localhost:9847 con:

Connections - gestisci connessioni (aggiungi, modifica, elimina), imposta password, testa la connettivita'
Query Log - consulta i log con filtri per connessione

Opzioni:

uv run mcp-query ui --port 8080        # Porta custom
uv run mcp-query ui --no-browser       # Non aprire il browser

Struttura file

~/.mcp-query/
  config.yaml                    # Configurazione connessioni
  logs/
    queries-2026-03-31.jsonl     # Log giornaliero

mcp-query/
  pyproject.toml
  src/mcp_query/
    __main__.py                  # CLI entry point
    server.py                    # MCP server + tools
    config.py                    # Config YAML + Keychain
    db.py                        # Connessioni + query + permessi
    audit.py                     # Logging JSONL
    ui.py                        # Web UI

Database supportati

Driver	Libreria	Note
`mysql`	PyMySQL	MySQL / MariaDB
`pgsql`	psycopg2	PostgreSQL
`sqlite`	sqlite3 (built-in)	Nessuna password necessaria

Available Tools

5 tools

describe_tableA

Show the structure of a database table (columns, types, keys).

Args: connection: Name of the database connection to use. table: Name of the table to describe.

Inputs: connection (required), table (required). Returns: result

list_connectionsA

List all configured database connections with their driver, database, and permission level.

Inputs: no named parameters. Returns: result

list_tablesA

List all tables in a database.

Args: connection: Name of the database connection to use.

Inputs: connection (required). Returns: result

queryA

Execute a SQL query on a database connection.

The query type is checked against the connection's allowed operations. Permissions can be a preset (read, write, admin) or a custom list of allowed operations (e.g. [select, insert]).

Multi-statement queries are blocked. SELECT queries have an automatic row limit.

Args: connection: Name of the database connection to use. sql: The SQL query to execute.

Inputs: connection (required), sql (required). Returns: result

query_logA

Show recent query audit log entries.

Args: connection: Filter by connection name (empty = all connections). limit: Maximum number of entries to return (default 20).

Inputs: connection, limit. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored 2026-05-26 12:35 across 5 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: describe_table for table structure, list_connections for available connections, list_tables for tables, query for executing SQL, and query_log for auditing. No overlaps.

Naming Consistency5/5

All tool names follow a consistent verb_object pattern in snake_case (e.g., describe_table, list_connections). No mixing of styles or vague verbs.

Tool Count5/5

With 5 tools, the server is well-scoped for its purpose of database querying. It covers essential operations without being too minimal or excessive.

Completeness4/5

The tool surface covers the main workflow: listing connections, exploring schema, executing queries, and auditing. Minor gap is lack of a tool to preview query result schema, but core functionality is complete.

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

SQL Server MCP by InsightfulPipeA
com.insightfulpipe
Hosted SQL Server MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Databases Developer Tools
41
https://mssql.insightfulmcp.com/
MANDATE Credential BrokerB
io.github.projetnanocorp
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Security
111
https://mandate.nanocorp.app/mcp
CData Connect AI
com.cdata
Cloud-hosted MCP server for secure AI access to enterprise data sources via CData Connect AI.
Databases RAG Systems Cloud Platforms
2
https://mcp.cloud.cdata.com/mcp
Contextflo
com.contextflo
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Databases Security
1
https://mcp.contextflo.com/mcp

Related MCP Servers

Mac Shell MCP Server
Shell Access Command Line OS Automation
cfdude
A
license
A
quality
B
maintenance
An MCP server that allows secure execution of macOS terminal commands through Claude or Roo Code with built-in security whitelisting and approval mechanisms.
Updated 11 days ago (2026-11-02 21:02 UTC)
8
6 npm
28
MIT
imessage-mcp
Communication OS Automation App Automation
camfortin
A
license
A
quality
C
maintenance
A local MCP server that enables reading iMessage conversations and sending new messages through Claude Desktop. It provides secure, read-only access to your Mac's iMessage database and AppleScript-based message sending capabilities.
Updated 3 months ago (2026-08-25 18:42 UTC)
6
MIT
MCP Database Bridge
Databases Developer Tools
buvaneswaraneb
F
license
Not graded
quality
C
maintenance
A secure, read-only MCP server that empowers Claude Desktop and AI agents to safely query and inspect local SQLite databases.
Updated 5 months ago (2026-06-22 16:26 UTC)
-
claude-work-mcp
File Systems Shell Access Developer Tools
blaspinto5
F
license
Not graded
quality
D
maintenance
A local MCP server that connects Claude Code to your work environment through auditable tools for file operations, API calls, and command execution, with safety gates and configuration.
Updated 4 months ago (2026-07-10 19:53 UTC)
-