What is Usqlmcp

usqlmcp is a universal SQL MCP (Model Context Protocol) designed to facilitate SQL database interactions through a standardized protocol.

Use cases

Use cases for usqlmcp include executing queries in development environments, managing database schemas, and integrating SQL capabilities into applications via Docker.

How to use

To use usqlmcp, download the appropriate release for your platform, extract the executable, and add it to your system’s PATH. Configure it in your MCP settings, either in the ~/.cursor/mcp.json file or through the Cursor settings menu.

Key features

Key features of usqlmcp include tools for executing SELECT queries, modifying data with INSERT, UPDATE, DELETE, and ALTER commands, and creating new tables in the database.

Where to use

usqlmcp can be used in various fields that require database management and SQL query execution, including software development, data analysis, and application integration.

usqlmcp

A universal SQL MCP (Model Context Protocol).

Features

• Tools

  • read_query: Execute a SELECT query and return the results.
  • write_query: Execute an INSERT, UPDATE, DELETE, or ALTER query and return the number of affected rows.
  • create_table: Execute a CREATE TABLE query to define new tables in the database.
  • describe_table_schema: Get the JSON schema for a given table, including column names and data types, for all supported databases.

• Resources

  • usqlmcp://<table>/schema: Access table schema as JSON resource for any table in the database.
  • Individual table schema resources are automatically discovered and registered for each table.

Installing

usqlmcp is available via Release

Installing via Release

1. Download a release for your platform
2. Extract the usqlmcp or usqlcmp.exe file from the .tar.bz2 or .zip file
3. Move the extracted executable to somewhere on your $PATH (Linux/macOS) or
   %PATH% (Windows)

Setup

MCP Integration in Cursor

Add the following configuration to your ~/.cursor/mcp.json file or configure via the settings menu in Cursor.

{
  "mcpServers": {
    "usqlmcp": {
      "command": "usqlmcp",
      "args": [
        "--dsn",
        "sqlite3:///your/db/dsn/file.db"
      ]
    }
  }
}

Other tools

{
  "servers": {
    "usqlmcp": {
      "type": "stdio",
      "command": "usqlmcp",
      "args": [
        "--dsn",
        "sqlite3:///your/db/dsn/file.db"
      ]
    }
  }
}

Docker Usage

You can configure usqlmcp to run via Docker in Cursor by specifying the appropriate command and arguments in your MCP JSON configuration.

Example: Postgres (Docker)

Add the following to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "usqlmcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/thesoulless/usqlmcp:latest",
        "--dsn",
        "postgres://username:[email protected]:5432/dbname?sslmode=disable"
      ]
    }
  }
}

Note: When connecting to a database on your host machine, use host.docker.internal instead of localhost or 127.0.0.1.

Example: SQLite with Volume Mounting (Docker)

To use a SQLite database file from your local machine, add the following to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "usqlmcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "/path/to/local/mydatabase.db:/data/mydatabase.db",
        "ghcr.io/thesoulless/usqlmcp:latest",
        "--dsn",
        "sqlite3:///data/mydatabase.db"
      ]
    }
  }
}

This mounts your local SQLite database file directly into the container, providing access to only what’s needed.

Acknowledgments

This project depends on usql, a universal command-line interface for SQL databases.