django-mcp-sql

Let an LLM agent — like Claude Code — run read-only SQL against your PostgreSQL database over the Model Context Protocol, without handing it a database login or the ability to write anything.

In one line: the self-hosted, Postgres-only safe-execution-and-access-control layer that gives Django shops the part of QueryBear a SaaS can't — an agent reading a precisely-scoped slice of your database, with your database credentials never leaving your infrastructure and the agent able to reach only the slice you expose, never a login or the rest of your data. Bring your own SQL-writing agent. (How it compares — and where your data actually goes.)

It already runs in production, mediating an LLM agent's database access inside a larger Django application — this package is an extraction of that code, not a greenfield experiment.

It's safe by construction, not by asking the model nicely. Even a confused or hijacked agent can only ever touch the slice of data you chose to expose — four independent layers enforce it, so a bypass has to beat all four:

• It sees only what you expose. Each access profile's whitelist points at the specific tables — or, better, curated row- and column-limited views — you pick. You can hand the agent a view that drops the sensitive columns and filters the rows, and the underlying table stays invisible: a login-less Postgres role simply holds no SELECT on anything off the list, so "invisible" is enforced by the database, not by trust. (Run several profiles to give different agents different slices.)

• It only runs SELECT. Every statement is parsed and checked first; anything that isn't a single read-only query is rejected before it reaches the database.

• It runs in a sandbox. Queries execute in a locked-down, time-limited transaction that can't linger or mutate.

• Nothing reaches it unauthenticated. The endpoint sits behind OAuth 2.1 with PKCE (RFC 7591/8414/9728 discovery); an unauthenticated client can't even open the door.

Where your data actually goes

This package never ships your database anywhere. Your Postgres credentials stay put — the agent authenticates to you over OAuth and never holds a database login — and anything you didn't whitelist stays invisible, enforced by a role that genuinely can't read it.

What the agent does receive is the slice you chose to expose: the rows a query returns and the schema of the tables you allowed. Those bytes go wherever the agent runs. Point a cloud model like Claude at the endpoint and the rows it reads travel to that model's provider, exactly like any other prompt — and no library on the database side can change that.

Want the queried slice to stay on your hardware too? Run a local agent against the same endpoint: the access-control and audit story is identical, and then nothing leaves at all. So the product doesn't keep your data in — it controls which rows an agent can ever reach, and logs every one that moves. Pick your agent accordingly.

Status: beta. The public API and settings shape are stabilizing, but may still shift before 1.0. The PyPI badge above shows the current release.

Quickstart — try it in 5 minutes

The fastest way to see this work is the bundled example app — a vanilla Django project (auth.User, stock sessions, no allauth) that wires the package end to end, including a two-tier curated-view setup. You don't have to touch your own project to watch Claude Code query a database.

git clone https://github.com/thepapermen/django-mcp-sql
cd django-mcp-sql/example

# Needs `uv` and a reachable PostgreSQL. See example/README.md for the one-time
# login-role snippet and the EXAMPLE_PG_* connection defaults.
make install                                       # venv + editable install of the package
make createdb migrate roles grants bootstrap_demo  # db, migrations, PG roles + grants, demo users
make runserver                                     # serves http://127.0.0.1:8001/

# In another terminal, register it with Claude Code — then just ask Claude to use it:
claude mcp add --transport http mcp-sql-example http://127.0.0.1:8001/mcp/sql/

The first tool call kicks off the OAuth dance (log in as demo / demo); after that, list_tables and run_query work against the demo data. The full walkthrough — the OAuth flow, the second access tier, the MFA note — is in the example README.

Ready to wire it into your own project? See Installation below.

Related MCP server: moat-mcp

What you get

Three MCP tools mounted at /mcp/sql/:

Every call writes one append-only MCPQueryLog audit row. Every auth rejection writes one MCPAuthRejectionLog row (the resolved-user gates, including a gate that fails with an error, which is a denial too; anonymous / bad-token probing goes through Django-cache counters with a silent per-IP block, not the audit table — use a shared cache backend (Redis, Memcached) in production: with a per-process backend like LocMem the counters, and therefore the block, are per-worker).

Observability — per-user query-volume tripwires (one ERROR per (user, decision, window) crossing of VOLUME_ALERT_THRESHOLDS; alerts, never blocks), an ERROR when a user is added to the MCP permission group, and read-only Django admin browsers for both audit tables plus a per-user usage-summary view (allowed / rejected / auth-rejection counts per rolling window). The package emits logger.error only — wire a Sentry LoggingIntegration(event_level=logging.ERROR) to receive these as events; the package itself never imports sentry_sdk.

Security model — prompt injection & untrusted data

Postgres-only by design

The package depends on Postgres features that don't port: SET LOCAL ROLE into a NOLOGIN role, statement_timeout / lock_timeout / idle_in_transaction_session_timeout / default_transaction_read_only / standard_conforming_strings GUCs (and search_path, with the opt-in pin), PG-only error codes (57014, 42501), CREATE OR REPLACE VIEW semantics, sqlglot's dialect='postgres'. There is no design path to MySQL / SQLite without a parallel implementation — hence django-mcp-sql not django-mcp-mysql etc.

How it compares

Most "AI + your database" tools are hosted services that write the SQL for you: you connect a database, ask a question in English, the service generates a query, runs it on its infrastructure, and hands back rows. Products like QueryBear work this way. They're a good fit when you want answers fast and don't mind your queries — and sometimes your data — passing through someone else's servers.

django-mcp-sql is the other half of that stack. It does not generate SQL and it is not a service. The agent (Claude Code, or anything that speaks MCP) writes the SQL; this package is the part that decides whether that SQL is allowed to run, runs it safely, and records it. It's a library you embed in a Django app you already operate.

It isn't really a feature-by-feature contest — it's a fork in the road:

Pick a hosted service if you want natural-language answers with the least setup. Pick this if you already run a Django + Postgres app and want access that's enforced by four independent layers and auditable line by line — not safe because you trusted a prompt or a vendor. And if your data genuinely can't leave your perimeter, pair it with a local agent (see Where your data actually goes) so the queried slice stays on your hardware too.

Installation

pip install django-mcp-sql
# Optional extras
pip install "django-mcp-sql[allauth]"   # wire MFA gate to allauth.mfa.utils.is_mfa_enabled

Then in your Django settings:

INSTALLED_APPS = [
    # ... your apps ...
    "rest_framework",
    "oauth2_provider",
    "mcp_sql",
]

DATABASES = {
    "default": { ... },
    # Required: dedicated read-only alias. The executor asserts
    # connection.alias == MCP_SQL["DB_ALIAS"] before issuing any SELECT.
    "mcp_readonly": {
        # ... pointed at the same database as default but as a non-superuser ...
        "OPTIONS": {"application_name": "mcp-readonly"},
        "ATOMIC_REQUESTS": False,
        "CONN_MAX_AGE": 0,
    },
}

DATABASE_ROUTERS = ["mcp_sql.db_router.McpSqlRouter"]

# Every MCP_SQL key has an in-package default (see `mcp_sql/conf.py` DEFAULTS),
# so declare only what you change. Two things are worth setting on day one:
# each profile's ALLOWED_MODELS (the default whitelist is empty, so nothing is
# readable) and MFA_CHECKER (the default denies every user). Both defaults are
# useless-but-safe on purpose — an unconfigured install grants nothing.
MCP_SQL = {
    # One entry per access tier. The `default` profile below is the
    # single-tier setup; add more for multi-tier, each with its own unique
    # ROLE / PERMISSION_CODENAME / GROUP_NAME. See docs/architecture.md
    # "Profiles".
    "PROFILES": {
        "default": {
            "ROLE": "mcp_readonly_role",  # NOLOGIN PG role entered via SET LOCAL ROLE
            "PERMISSION_CODENAME": "use_mcp_session",  # binds a user to this tier
            "GROUP_NAME": "mcp_sql_users",
            "ALLOWED_MODELS": [
                "auth.Permission",  # your real whitelist goes here
            ],
            # "SESSION_CONTEXT": "your_app.scoping.context",  # optional per-row hook
        },
    },
    # MFA gate (fail-closed) — set this before onboarding anyone. The default
    # `deny_unconfigured_mfa` returns False for EVERY user, so the whole MCP
    # surface is locked out (the app logs a startup WARNING) until you wire a
    # real check. django-allauth projects use:
    # "MFA_CHECKER": "allauth.mfa.utils.is_mfa_enabled",
    #
    # Declared clients — Claude.ai, ChatGPT, and Cursor's hosted agents ship
    # ON. Each provisions a public/PKCE `Application` at `migrate`; run
    # `manage.py mcp_sql_clients` for the client_id to paste into the
    # provider's connector (secret blank). They need a public HTTPS origin to
    # be reachable, and are inert until someone actually connects one.
    # A declared key replaces its default wholesale, so `"CLIENTS": {}` runs
    # loopback-only and a smaller dict keeps just what it names.
    # See docs/oauth.md "Clients".
    # "CLIENTS": {},
    #
    # Other overrides, all defaulted — see `mcp_sql/conf.py` DEFAULTS:
    # "RESOURCE_NAME": "My App",
    # "BAN_SELECT_STAR": True,
    # "LIMITS": {"DEFAULT_LIMIT": 10, "HARD_LIMIT": 100, "BYTES_LIMIT": 256 * 1024},
    # Per-user volume tripwires: {decision: {window_seconds: threshold}}.
    # Crossing emits one Sentry ERROR per (user, decision, window) bucket;
    # it alerts, it never blocks.
    # "VOLUME_ALERT_THRESHOLDS": {
    #     "allowed": {3600: 50, 86400: 150},
    #     "rejected": {3600: 50, 86400: 150},
    # },
    # "BAD_TOKEN_IP_THRESHOLD": 100,
    # "BAD_TOKEN_IP_WINDOW_SECONDS": 21600,
    # "SESSION_MODEL": "your_app.Session",  # opt-in runtime session-existence gate;
                                            # must be a session model with a `user` FK
                                            # (stock `django.contrib.sessions.Session`
                                            # does NOT qualify — its absence of a `user`
                                            # column is why the default is `None`)
    # Opt-in refresh tokens (default 0 = OFF): rotating, and refused once this
    # many seconds have passed since the user's consent. See docs/oauth.md
    # "Refresh tokens (opt-in)".
    # "REFRESH_TOKEN_MAX_AGE_SECONDS": 7 * 24 * 3600,
    # search_path pin — RECOMMENDED, but off by default (False). On, every
    # read transaction runs SET LOCAL search_path = public, pg_temp, so an
    # unqualified table name is the whitelisted one in `public`. Off, names
    # resolve through the database's own search_path: any role with CREATE
    # on the database (a schema named after the profile role) or another
    # session on the same backend (a temporary relation, e.g. under
    # transaction-mode pgbouncer) can plant a same-named relation readable
    # through a grant to PUBLIC, without any right on your tables, and the
    # agent reads its rows under the whitelisted name; mcp_sql_grants does
    # not detect it. Leave it off only if an extension the agent uses lives
    # outside `public` — and even then, with it on, the agent can write
    # `ext.f(x)` / `OPERATOR(ext.op)`.
    # See docs/architecture.md "`search_path` is pinned only on request".
    "PIN_SEARCH_PATH": True,
}

OAUTH2_PROVIDER = {
    "OAUTH2_VALIDATOR_CLASS": "mcp_sql.oauth.MCPOAuth2Validator",
    "SCOPES": {"mcp:sql": "Read-only SQL surface for MCP agents"},
    "DEFAULT_SCOPES": ["mcp:sql"],
    "ACCESS_TOKEN_EXPIRE_SECONDS": 6 * 3600,
    # Moot for MCP: the package's OAuth endpoints mint no refresh tokens and
    # refuse every refresh grant unless MCP_SQL["REFRESH_TOKEN_MAX_AGE_SECONDS"]
    # opts in (with its own hard cap from the consent), so
    # ACCESS_TOKEN_EXPIRE_SECONDS is the re-consent interval. (On its own,
    # DOT reads 0 as "no age limit".)
    "REFRESH_TOKEN_EXPIRE_SECONDS": 0,
    "AUTHORIZATION_CODE_EXPIRE_SECONDS": 60,
    # The package requires PKCE (S256 only) whatever this says.
    "PKCE_REQUIRED": True,
    # Recommended (DOT 3.4.1+): refuse any request carrying an `access_token`
    # in the URL query string outright, without DOT's per-request warning.
    # The package never accepts such a token either way.
    "COMPLIANT_BCP_RFC9700_ACCESS_TOKEN_TRANSPORT": True,
    # ALLOWED_REDIRECT_URI_SCHEMES is deliberately NOT set: DOT already
    # defaults it to ["http", "https"], which covers both shapes this package
    # admits (RFC 8252 loopback and the declared clients' https callbacks).
    # It is install-global — it governs redirect handling for every OAuth
    # application in your project — so narrowing it is a decision to make on
    # purpose, not by pasting. If you do narrow it, the app refuses to boot
    # (and says why) unless it keeps "http" — always, because /o/register
    # mints RFC 8252 loopback callbacks — and "https" while any https client
    # is declared.
}

Wire the URLs in your project's urls.py:

urlpatterns = [
    # ... your routes ...
    path("", include("mcp_sql.urls")),
]

Then run the DBA setup once per environment (creates the mcp_readonly_role Postgres role + role-level guard GUCs):

psql -U <superuser> -d <database> \
    -v app_role=<your_app_role> \
    -f $(python -c "import mcp_sql, os; print(os.path.join(os.path.dirname(mcp_sql.__file__), 'sql/role_setup.sql'))")

Then apply migrations and the SELECT grants:

python manage.py migrate
python manage.py mcp_sql_grants --apply

Documentation

The architecture / design doc and the full operational runbooks ship inside the package (importable consumers find them under mcp_sql/docs/):

• docs/architecture.md — design, file map, settings shape, OAuth surface, curated-view pattern, the complete "Watch out" list.

• docs/role-setup.md — DBA setup, grants reconciliation, sanity checks.

• docs/oauth.md — OAuth issuance gate, MCP client registration, incident response.

Compatibility

• Python: 3.11–3.14 (which ones depends on the Django line — see the table below)

• Postgres: 14+ on Django 4.2–6.0, 15+ on Django 6.1 (Django 6.1 itself refuses to connect to 14). The package's own SQL (pg_has_role, information_schema.role_table_grants, SET LOCAL ROLE, CREATE OR REPLACE VIEW) works on earlier versions too, but CI only tests PostgreSQL 14, 15 and 16.

Supported combinations

The package's own surface is Django-version-agnostic; the version coupling comes from DRF, which gained each Django line in a later release, plus Django's own PostgreSQL floor. Support is therefore a staircase — a higher Django needs a higher minimum DRF:

• The DRF floor is 3.14 — the lowest we support, i.e. what a legacy Django 4.2 app is likely already pinning. Each Django line has its own DRF minimum (5.x from 3.15, 6.0 from 3.17, 6.1 from 3.18). A fresh pip install always resolves the newest DRF your Django allows (3.18 on 5.2+; 3.17 on 4.2, since DRF 3.18 requires Django ≥ 5.2); the older DRF columns matter only when adopting the package into an app that already pins one.

• Django 6.1 needs DRF ≥ 3.18, and pip will not enforce it. DRF ≤ 3.17 fails to import on Django 6.1 (rest_framework.views imports django.utils.cache.cc_delim_re, which 6.1 removed), yet declares django>=4.2 with no upper cap — so upgrading Django to 6.1 under an existing DRF ≤ 3.17 pin installs cleanly and then fails with an ImportError as soon as the URLconf loads (e.g. manage.py check). This package can't declare it either: a DRF floor that depends on the Django version isn't expressible in package metadata, and a flat >=3.18 floor would drop Django 4.2. Upgrade DRF together with Django.

• Django 6.1 requires PostgreSQL 15+: it refuses to connect to 14 (NotSupportedError). Django 4.2–6.0 run on 14+.

• Django 6.0 drops Python 3.11; Django 4.2 has no Python 3.13; Python 3.14 is tested on Django 6.0 and 6.1 only — hence the ragged Python columns.

• Django 4.2 is end-of-life upstream. Its last release, 4.2.30, shipped on 2026-04-07; security fixes published since then ship only for Django 5.2 and later. The package keeps supporting 4.2 for apps that can't move yet, but running it is a risk you carry — plan the upgrade.

• django-oauth-toolkit, oauthlib, mcp, sqlglot, a2wsgi, and pydantic are not Django-version-coupled within their declared ranges. django-oauth-toolkit is floored at 3.4.1 on every row: earlier releases have an unauthenticated open redirect at /o/authorize/ (DOT #1719, fixed in 3.4.0) and match redirect URIs loosely (exact since 3.4.1, RFC 9700 §2.1). Every supported release stores an RFC 8707 resource on a token and audience-checks it (see docs/oauth.md). No DOT release declares Django 6.1 yet; the suite passes on 6.1 with DOT 3.4.1. oauthlib (3.3.0+, below

  5. is declared directly because the package builds its OAuth server from oauthlib's classes.

Dropping into an existing app with an older pinned DRF

When you install the package into an existing project that already pins an older DRF, that project's pins win — the package's floor does not force an upgrade. The package's narrow DRF surface (an OAuth2Authentication subclass, @api_view, IsAuthenticated) is verified to run on DRF 3.14 with Django 4.2 by a dedicated CI leg, even though a greenfield install would never select that pair. So a Django 4.2 app on DRF 3.14 can adopt the package without touching its DRF pin. (DRF 3.14 + Django ≥ 5.0 is not supported — DRF 3.14 predates those Django lines.)

MFA / django-allauth

The allauth extra (django-mcp-sql[allauth]) wires the TOTP gate to django-allauth[mfa] >= 65.14. On a project running an older allauth without allauth.mfa, skip the extra and point MCP_SQL["MFA_CHECKER"] at your own 2FA predicate — the core package has no hard allauth dependency.

The standalone suite (make test, settings in tests/settings.py) runs in CI (.github/workflows/ci.yml) across every row above, plus pinned floor legs and the DRF 3.14 + Django 4.2 legacy leg, against PostgreSQL 14 (Django ≤ 6.0), 15 (Django 6.1, plus one 6.0 leg) and 16 (one 6.0 leg).

Postgres role setup

Once per environment, a DBA with PG superuser rights applies sql/role_setup.sql to create the mcp_readonly_role role + the role-level guard GUCs (statement_timeout, lock_timeout, idle_in_transaction_session_timeout, default_transaction_read_only, standard_conforming_strings — the executor also sets each per transaction with SET LOCAL; the search_path = public, pg_temp default, commented out in the file, is for installs that turn on MCP_SQL["PIN_SEARCH_PATH"]) and grant the role membership to the consuming app's PG user. The script is idempotent and is parameterised by a -v app_role=<role> psql variable so a single SQL file works across deployments whose app role differs.

psql -h <pg_host> -U <pg_superuser> -d <database> \
    -v app_role=<app_pg_role> \
    -f sql/role_setup.sql

# Verify:
psql -h <pg_host> -U <pg_superuser> -d <database> -c "\du mcp_readonly_role"
# Expected: row present, "Cannot login".

After the role exists, apply the package's migrations and reconcile the table-level SELECT grants:

python manage.py migrate
python manage.py mcp_sql_grants --apply

See docs/role-setup.md for the full DBA-facing runbook (drift detection, CI gates, troubleshooting).

Development

Run the package's own test suite (needs uv and a reachable PostgreSQL — see tests/settings.py for the MCP_SQL_TEST_PG_* connection env vars. Bootstrap mcp_readonly_role via sql/role_setup.sql first — several tests enter it with SET LOCAL ROLE — and connect as a superuser so the role-isolation tests run instead of skipping):

make test

Build the distribution and verify the wheel installs cleanly into a fresh venv (Django-independent imports + package-data presence):

make build              # produces ./dist/django_mcp_sql-<version>-py3-none-any.whl + .tar.gz
make test-install       # ephemeral build + venv install + import & package-data smoke

All targets require uv on PATH (install once: curl -LsSf https://astral.sh/uv/install.sh | sh). Release/extraction mechanics live in RELEASING.md; contribution expectations in CONTRIBUTING.md.

License

MIT.