sql-mini-mcp

A read-only SQL Server MCP server for coding agents: 6 metadata tools, no unrestricted SQL.

Read the data. Protect the identity.

General-purpose database MCP servers hand the agent a raw SQL prompt and dozens of tools. This server gives a coding agent the schema knowledge it needs to write correct code - servers, databases, tables, columns, keys, indexes, stored procedures - and nothing that can change or leak data.

• 6 tools, all read-only - every one is annotated read-only and earns its place in context; see tools.

• No caller-provided SQL - the server never executes SQL an agent wrote. Metadata comes from SQLAlchemy Inspector and fixed catalog queries.
• Your aliases, not your network - the agent sees only the server aliases you configure. There is no network discovery, and the catalog is not published as MCP resources.
• Secrets stay out of sight - connection URLs live in YAML with ${NAME} placeholders resolved from the environment. They never appear in logs or model-visible errors.
• Compact, predictable output - object-rooted results with stable sorting, literal case-insensitive name filters, and stored procedure lists that do not expand definitions.
• Errors an agent can act on - an ambiguous name lists the candidate schemas. Errors never contain connection details, credentials, or rows.
• Fails closed - security decisions are allowlists; anything unrecognized is refused.
• On PyPI - uvx sql-mini-mcp, no repo clone required.

• Install
• Configure
• Security
• Contributing and security

More detail lives in docs/: the configuration reference and what the tools return.

Install

uvx sql-mini-mcp

or

pip install sql-mini-mcp

Pin a version when you want a fixed surface: uvx sql-mini-mcp==1.0.0.

Requires Python 3.12+, uv (or pip), and Microsoft ODBC Driver 18 for SQL Server.

Configure

Copy sql-mini-mcp.example.yaml to sql-mini-mcp.yaml, list your servers, and keep credentials in environment variables:

version: 1
servers:
  reporting:
    engine: sqlserver
    access_level: metadata
    connection_url: "${REPORTING_SQL_URL}"

Point the server at the file with SQL_MINI_MCP_CONFIG (or --config), and check it without connecting to any database:

SQL_MINI_MCP_CONFIG=sql-mini-mcp.yaml uvx sql-mini-mcp --check-config

Configuration is validated at startup, and an error names the problem without printing a URL or secret. Keep credentials in the host's own configuration and never commit them. The server acts with the database account's permissions, so use a dedicated login with the least access the job needs. Every setting, including the runtime limits, is in configuration.md.

claude mcp add --env SQL_MINI_MCP_CONFIG=/path/to/sql-mini-mcp.yaml --env REPORTING_SQL_URL=mssql+pyodbc://... --transport stdio sql-mini -- uvx sql-mini-mcp

{
  "mcpServers": {
    "sql-mini": {
      "command": "uvx",
      "args": ["sql-mini-mcp"],
      "env": {
        "SQL_MINI_MCP_CONFIG": "/path/to/sql-mini-mcp.yaml",
        "REPORTING_SQL_URL": "mssql+pyodbc://..."
      }
    }
  }
}

codex mcp add sql-mini --env SQL_MINI_MCP_CONFIG=/path/to/sql-mini-mcp.yaml --env REPORTING_SQL_URL=mssql+pyodbc://... -- uvx sql-mini-mcp

Security

The MCP caller, SQL input, database metadata, rows, and tokens are untrusted; the operator, the process environment, and the database credentials are the trusted boundary. Database permissions remain the primary authorization control - this server never widens them. The full model, and how to report a vulnerability, are in SECURITY.md.

Contributing and security

Setup, checks, the test commands, the branch and commit conventions, and the release model are in CONTRIBUTING.md. Report vulnerabilities privately as described in SECURITY.md. Changes that affect someone running the server are recorded in CHANGELOG.md.

License

MIT.