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 "Install 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 Related Servers Score Discussions

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.

ParametersJSON Schema

Name	Required	Description	Default
`connection`	Yes
`table`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description explains output but does not mention side effects, permissions, or limitations. Adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with purpose. No unnecessary words. Efficient and easy to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Has output schema, so return values are covered. Description covers purpose and parameters adequately. Could mention explicit fields returned, but already says 'columns, types, keys'.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description adds essential meaning: 'connection' is a connection name, 'table' is a table name. Clear and helpful.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool shows table structure including columns, types, and keys. Distinguishes from siblings like query and list_tables.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives like query or list_tables. Agent must infer from context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_connectionsA

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

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description implies a read-only operation ('List all...'), which aligns with the tool's intent. However, it does not disclose any potential side effects, authentication needs, or behavior when no connections exist. Given no annotations, it is mostly clear but could be more thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently conveys the purpose and output. Every word is necessary, and there is no extraneous information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no parameters, has an output schema), the description adequately covers what an agent needs to know. It could mention prerequisite permissions or the format of the list, but it is largely sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has no parameters, so the description adds no parameter meaning—this is appropriate. Schema description coverage is 100%, meeting the baseline perfectly.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses the specific verb 'List' and identifies the resource 'all configured database connections' along with the details returned (driver, database, permission level). This clearly distinguishes it from sibling tools which focus on tables and queries.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description does not provide any guidance on when to use this tool versus alternatives. While the sibling names offer some context, the description itself lacks explicit usage instructions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_tablesA

List all tables in a database.

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

ParametersJSON Schema

Name	Required	Description	Default
`connection`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.5/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It does not disclose any behavioral traits (e.g., read-only nature, potential failures, performance implications). Simply states it lists tables without side-effect details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Extremely concise: one sentence plus a single-parameter description. Purpose is front-loaded with no unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given an output schema exists and it's a simple list operation, the description is minimally adequate. However, it lacks context about what 'tables' means (e.g., system vs. user tables) and any edge cases (e.g., invalid connection).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description adds an 'Args' section explaining the connection parameter as 'Name of the database connection to use.' This adds meaning beyond the schema's type-only definition.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'List all tables in a database.' It uses a specific verb and resource, and distinguishes from siblings like describe_table (describes a single table) and list_connections (lists connections).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. Does not mention prerequisites, exclusions, or scenarios where other tools like describe_table or query might be more appropriate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema

Name	Required	Description	Default
`connection`	Yes
`sql`	Yes

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Discloses important behaviors: query type checked against allowed operations, multi-statement queries blocked, and automatic row limit for SELECT. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured with a clear one-line summary followed by bullet-like details. Not overly verbose, though some redundancy exists. Efficient for its content.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers key behavioral aspects (permissions, multi-statement block, row limit). Has output schema, so return values not needed. Lacks error handling details, but overall adequate for a query tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so description must add meaning. Mentions connection is 'name of the database connection' and sql is 'the SQL query', but lacks details on formats, constraints, or allowed values. Behavioral aspects are more about the tool than parameter specifics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states it executes a SQL query on a database connection, with a specific verb and resource. It distinguishes from sibling tools like describe_table, list_connections, list_tables, and query_log which cover different aspects of database interaction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides context on query type checking, multi-statement blocking, and row limits, but does not explicitly guide when to use this tool versus alternatives like describe_table or query_log. No when-not or sibling comparisons.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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).

ParametersJSON Schema

Name	Required	Description	Default
`connection`	No
`limit`	No

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.6/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It only states 'show recent query audit log entries' without disclosing behavioral traits like ordering, time range, user scope, or whether it requires admin access. The description is minimal.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise, using two sentences plus bullet-like parameter explanations. No redundant information, though the structure could be improved with clearer separation of purpose and parameter details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema assumed present, return values are covered. However, the description lacks context on ordering, time range, or user-specific scoping. Siblings help differentiate, but missing details limit completeness for an audit log tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description adds value by explaining each parameter: 'connection: Filter by connection name (empty = all connections)' and 'limit: Maximum number of entries to return (default 20)'. This clarifies defaults and semantics beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states 'Show recent query audit log entries', specifying verb (show) and resource (audit log entries). It effectively distinguishes from siblings like 'describe_table' and 'query'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for viewing audit logs but lacks explicit guidance on when to use this tool versus alternatives like 'query' or 'list_tables'. No when-not-to-use or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

5 tool updatesv0.1.0May 26, 2026
- First observeddescribe_table
- First observedlist_connections
- First observedlist_tables
- First observedquery
- First observedquery_log

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0

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

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

MANDATE Credential Broker B
io.github.projetnanocorp
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
111
CData Connect AIOAuth
com.cdata
Cloud-hosted MCP server for secure AI access to enterprise data sources via CData Connect AI.
Databases RAG Systems Cloud Platforms
2
ContextfloOAuth
com.contextflo
Query your warehouse or a CSV with Claude/ChatGPT over MCP, governed by table-level ACL + audit.
Databases Security
1
thoughtsOAuth
ai.thoughtbox.api
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Cloud Storage Finance
2

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 2 days ago (2026-09-04 07:14 UTC)
8
15
24
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 12 days 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 2 months ago (2026-06-22 16:26 UTC)
-
claude-work-mcp
File Systems Shell Access Developer Tools
blaspinto5
F
license
Not graded
quality
C
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 2 months ago (2026-07-10 19:53 UTC)
-

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/ottimis/mcp-query'

If you have feedback or need assistance with the MCP directory API, please join our Discord server