# QueryWeaver [Health: Active]

**Category:** 🗄️ Databases  
**Repository:** https://github.com/FalkorDB/QueryWeaver  
**GitHub Stars:** 1091  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/queryweaver

## Description
An MCP server for Text2SQL: transforms natural language into SQL using graph schema understanding.

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

```json
"mcpServers": {
  "queryweaver": {
    "command": "uvx",
    "args": ["queryweaver"]
  }
}
```

## Documentation

## What QueryWeaver MCP server does

QueryWeaver MCP server provides a Text2SQL interface for asking database questions in natural language. It uses graph-based schema understanding to represent databases through tables, columns, and foreign-key relationships, then uses that context to produce SQL and query results.

The application exposes both an HTTP MCP surface and a REST API. The MCP operations cover four parts of the workflow: listing available databases, connecting to a database, retrieving a database schema, and running a database query. The REST API adds graph management endpoints for creating or uploading schema graphs, listing user-scoped graphs, reading graph data, and submitting chat-based Text2SQL requests.

## How it works

A schema is stored as a graph associated with an authenticated user. The graph can be created from a JSON payload or an uploaded file. Once available, an agent can inspect the graph and send a natural-language request against a selected graph.

QueryWeaver MCP server returns generated SQL and query processing information through its MCP or REST interfaces. REST query responses are streamed as JSON messages separated by a defined message boundary. The stream may contain intermediate processing steps, follow-up questions for ambiguous requests, and the final SQL. Requests involving destructive SQL operations such as inserts, updates, or deletes include a confirmation step that an automated client must handle.

Per-user conversation memory is stored in FalkorDB. Memory graphs persist by default, but `MEMORY_TTL_SECONDS` can set an inactivity expiration period; the expiration is refreshed when the user interacts with the system.

## Setup and configuration

The provided Docker image starts the service on port 5000:

```bash
docker run -p 5000:5000 -it falkordb/queryweaver
```

Configuration can be supplied through a `.env` file passed with Docker's `--env-file` option or through individual environment variables. The documented configuration includes an application environment, a FastAPI secret key, OAuth credentials, and credentials for supported AI providers. QueryWeaver supports OpenAI, Gemini, Anthropic, and Azure provider keys.

The built-in MCP HTTP surface is enabled by default. Set `DISABLE_MCP=true` to turn it off. A client can target a local MCP endpoint at `http://127.0.0.1:5000/mcp` and send a bearer token in the `Authorization` header. REST operations that access or modify user-scoped data also require bearer-token authentication.

## Tools and capabilities

QueryWeaver MCP server registers these MCP operations:

- `list_databases` lists available databases.
- `connect_database` connects to a database.
- `database_schema` retrieves schema information.
- `query_database` runs a database query through the Text2SQL flow.

The REST API provides equivalent supporting workflows through graph endpoints. `GET /graphs` lists graphs, `GET /graphs/{graph_id}/data` returns graph nodes and links, `POST /graphs` creates or uploads a graph, and `POST /graphs/{graph_id}` submits a chat query. Graph identifiers are namespaced per user.

## Limitations and notes

MCP can be disabled through configuration, so clients cannot use the endpoint when `DISABLE_MCP` is set to `true`.

Generated queries may require clarification when a request is ambiguous or outside the available schema. Clients consuming the REST API must process its streamed message format and handle confirmation for destructive SQL. Authentication is required for user-scoped graphs and data. The documentation identifies FalkorDB as the store for conversation memory; it does not specify every database engine supported for query execution.

_Full upstream README: https://allmcps.com/mcp/queryweaver/readme_