# StackQL MCP Server [Health: Active]

**Category:** 🗄️ Databases  
**Repository:** https://github.com/stackql/stackql  
**GitHub Stars:** 1095  
**npm Downloads (last month):** 1010  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/stackql-mcp-server

## Description
SQL-native query and provisioning engine for cloud infrastructure, served over MCP.

## Tools
Capabilities this server exposes over MCP:

- **describe_method** — Full I/O contract for one method: every input with its param_type (input_required params become exact-match WHERE predicates; input_optional ones may be added) and every output field, which are the columns a SELECT or RETURNING can reference. Call it after list_methods and before the first query against a method; there is no resource-level equivalent because each method returns its own shape. Requires provider, service, resource, method.
- **list_methods** — Access methods for a resource with their SQL verb and required params. Pick the method whose verb matches the intent and whose required params you can supply, then describe_method it. Call when composing SQL from scratch against an unfamiliar resource; not needed when executing a vetted query library template. Requires provider, service, resource.
- **list_providers** — Available cloud/SaaS providers (top of the hierarchy). No inputs.
- **list_registry** — Providers (and their versions) available in the configured registry. Distinct from list_providers, which lists only providers already pulled. Optional provider arg lists versions for that provider.
- **list_resources** — Resources under a provider.service. Requires provider and service.
- **list_services** — Services under a provider. Requires provider.
- **pull_provider** — Install a single provider from the registry into the local approot cache. Requires provider; version is optional (latest published is pulled when empty). Writes only local cache state; no cloud control/data plane effect.
- **query_library_get** — Retrieve a query library entry by id. Without params: returns the raw template, param declarations and notes (adapt from it when no exact match exists). With params: the server validates values and returns rendered SQL plus which tool to execute it with (run_select_query or run_mutation_query). Read-only, no credentials.
- **query_library_search** — Search the curated StackQL query library by natural-language intent. Returns ranked template ids. Consult before composing SQL from scratch; follow with query_library_get, which validates params and surfaces any the index omits. Read-only, no credentials.
- **reload_credentials** — Live-reload provider credentials: re-sources the server's configured env file into the process environment, invalidates cached auth contexts, and reports resolution status for every installed provider (optional provider arg filters the report; changed field flags values that differ from before). Never returns secret values. Credentials resolve automatically at query time - never call this at session start or before queries. Call only after a query fails with a credential resolution error (fix the env file first, then reload, then retry) or when the user says credentials have been rotated or changed. If the report shows changed: false after a failure, the file was not updated - ask the user rather than retrying.
- **run_lifecycle_operation** — Execute a stackql EXEC lifecycle operation (eg EXEC aws.ec2.instances.start_instances ...). Real cloud side effects. Discover available operations and required params via list_methods and describe_method. Returns {messages, timestamp}. Gated by server mode.
- **run_mutation_query** — Execute INSERT/UPDATE/REPLACE/DELETE against the provider. Real side effects. Returns {messages, timestamp}. Gated by server mode. Consult query_library_search for a vetted template before composing SQL from scratch; when the SQL came from a library entry, pass its id as source.
- **run_select_query** — Execute a SELECT. Returns {rows}. Reads only; INSERT, UPDATE, DELETE and EXEC are refused in every mode. Consult query_library_search for a vetted template before composing SQL from scratch; when the SQL came from a library entry, pass its id as source.
- **server_info** — Get server identity and runtime: stackql version, backing SQL engine, provider registry location, mode, read-only flag. Call on demand - eg to diagnose a refused/gated operation or check version-specific behavior. Not needed at session start or before queries.
- **validate_select_query** — Parse and plan a SELECT without executing; the provider's credentials must still resolve, as for execution. Returns {valid, errors}. Use when iterating on syntax or plan errors, or pre-flighting complex/expensive queries - don't validate routinely; run_select_query surfaces the same errors.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "stackql-mcp-server": {
    "command": "npx",
    "args": ["-y","@stackql/mcp-server"]
  }
}
```

## Documentation

## What StackQL MCP Server does

StackQL MCP Server gives MCP clients an SQL-based interface to cloud and SaaS providers. StackQL translates SQL statements into API requests, sends them to the selected provider, and returns rows or operation messages. The underlying provider definitions come from the StackQL provider registry and describe the APIs, resources, inputs, and outputs available to the SQL layer.

The server supports both read-only inspection and operations that change remote state. SELECT queries return rows, while INSERT, UPDATE, REPLACE, and DELETE statements can make provider-side changes. Lifecycle actions are available through StackQL EXEC operations, such as starting an instance, when the server mode allows them.

## How it works

Provider access follows a hierarchy of provider, service, resource, and method. Agents can list installed providers, inspect registry contents, enumerate services and resources, then retrieve the HTTP methods available for a resource. `describe_method` supplies the exact input and output contract for a method, including required parameters and fields that can be selected or returned.

For query construction, `query_library_search` finds curated templates by natural-language intent. `query_library_get` can return a raw template or validate supplied parameters and produce rendered SQL together with the execution tool. Agents can also validate a SELECT plan before executing it. Query-library operations are read-only and do not require credentials.

Provider credentials resolve at query time. If credentials have been changed, `reload_credentials` can re-source the configured environment file, clear cached authentication contexts, and report resolution status without exposing secret values. `pull_provider` installs a provider into the local application cache and has no cloud control-plane effect.

## Setup and configuration

The server can run over stdio with:

```sh
stackql mcp --mcp.server.type=stdio
```

MCP clients can launch it through npm using `npx -y @stackql/mcp-server`, through PyPI using `uvx stackql-mcp-server`, or through Docker with the `stackql/stackql-mcp` image. Platform-specific `.mcpb` bundles are also distributed through the latest release. The project supports Windows, macOS, and Linux.

Add the selected launch command to the client's MCP server configuration. Provider credentials and the provider registry determine which APIs can be queried and which operations can be performed.

## Tools and capabilities

- Discover installed providers with `list_providers`, or inspect registry providers and versions with `list_registry`.
- Browse provider services and resources with `list_services` and `list_resources`.
- Inspect method contracts with `list_methods` and `describe_method`.
- Find and render vetted SQL templates with `query_library_search` and `query_library_get`.
- Execute reads with `run_select_query` and preflight SELECT statements with `validate_select_query`.
- Apply SQL mutations with `run_mutation_query` or execute lifecycle actions with `run_lifecycle_operation`.
- Install providers locally using `pull_provider` and inspect runtime details with `server_info`.
- Refresh changed credentials with `reload_credentials` after correcting the configured environment file.

## Limitations and notes

Mutation and lifecycle tools can have real cloud side effects and are gated by server mode. SQL must match the provider method contracts, including required parameters. `describe_method` is method-specific because different methods on the same resource can return different shapes. Credential reloads should follow a credential-resolution failure or an explicit credential rotation, rather than being called at the start of every session.

_Full upstream README: https://allmcps.com/mcp/stackql-mcp-server/readme_

