sql-mcp 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- sql_mcp/__init__.py +64 -0
- sql_mcp/__main__.py +4 -0
- sql_mcp/agent_server.py +71 -0
- sql_mcp/api/__init__.py +9 -0
- sql_mcp/api/api_client_sql.py +469 -0
- sql_mcp/api_client.py +11 -0
- sql_mcp/auth.py +142 -0
- sql_mcp/dialects.py +183 -0
- sql_mcp/main_agent.json +14 -0
- sql_mcp/mcp/__init__.py +5 -0
- sql_mcp/mcp/mcp_sql.py +224 -0
- sql_mcp/mcp_config.json +33 -0
- sql_mcp/mcp_server.py +59 -0
- sql_mcp/safety.py +173 -0
- sql_mcp/sql_input_models.py +63 -0
- sql_mcp/sql_response_models.py +51 -0
- sql_mcp-0.1.0.dist-info/METADATA +242 -0
- sql_mcp-0.1.0.dist-info/RECORD +22 -0
- sql_mcp-0.1.0.dist-info/WHEEL +5 -0
- sql_mcp-0.1.0.dist-info/entry_points.txt +3 -0
- sql_mcp-0.1.0.dist-info/licenses/LICENSE +21 -0
- sql_mcp-0.1.0.dist-info/top_level.txt +1 -0
sql_mcp/safety.py
ADDED
|
@@ -0,0 +1,173 @@
|
|
|
1
|
+
"""Read-only statement gate for sql-mcp (CONCEPT:SQL-1.3).
|
|
2
|
+
|
|
3
|
+
``sql_query`` accepts only read statements. The gate strips string literals,
|
|
4
|
+
quoted identifiers, and comments, then classifies the statement by its first
|
|
5
|
+
significant keyword against an allowlist (``SELECT``, ``WITH``, ``EXPLAIN``,
|
|
6
|
+
``SHOW``, ``DESCRIBE``, ``PRAGMA``, ``VALUES``). CTEs are inspected at paren
|
|
7
|
+
depth zero so ``WITH ... INSERT`` cannot smuggle a write, ``SELECT ... INTO``
|
|
8
|
+
is rejected, and multi-statement payloads are refused outright. Writes go
|
|
9
|
+
through ``sql_execute`` and only when the server was started with
|
|
10
|
+
``SQL_ALLOW_WRITES=True``.
|
|
11
|
+
"""
|
|
12
|
+
|
|
13
|
+
import re
|
|
14
|
+
|
|
15
|
+
READ_ONLY_STARTERS = {
|
|
16
|
+
"select",
|
|
17
|
+
"with",
|
|
18
|
+
"explain",
|
|
19
|
+
"show",
|
|
20
|
+
"describe",
|
|
21
|
+
"desc",
|
|
22
|
+
"pragma",
|
|
23
|
+
"values",
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
MUTATING_KEYWORDS = {
|
|
27
|
+
"insert",
|
|
28
|
+
"update",
|
|
29
|
+
"delete",
|
|
30
|
+
"merge",
|
|
31
|
+
"replace",
|
|
32
|
+
"truncate",
|
|
33
|
+
"create",
|
|
34
|
+
"alter",
|
|
35
|
+
"drop",
|
|
36
|
+
"grant",
|
|
37
|
+
"revoke",
|
|
38
|
+
"call",
|
|
39
|
+
"exec",
|
|
40
|
+
"execute",
|
|
41
|
+
"set",
|
|
42
|
+
"copy",
|
|
43
|
+
"vacuum",
|
|
44
|
+
"attach",
|
|
45
|
+
"detach",
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
_TOKEN_RE = re.compile(r"[A-Za-z_][A-Za-z0-9_]*|\(|\)|;")
|
|
49
|
+
|
|
50
|
+
|
|
51
|
+
class StatementNotAllowedError(ValueError):
|
|
52
|
+
"""Raised when a statement violates the read-only or single-statement gate."""
|
|
53
|
+
|
|
54
|
+
|
|
55
|
+
def strip_literals_and_comments(sql: str) -> str:
|
|
56
|
+
"""Replace string literals, quoted identifiers, and comments with spaces.
|
|
57
|
+
|
|
58
|
+
Keeps offsets stable so keyword scanning cannot be fooled by SQL keywords
|
|
59
|
+
embedded in strings, quoted identifiers, or comments.
|
|
60
|
+
"""
|
|
61
|
+
out: list[str] = []
|
|
62
|
+
i, n = 0, len(sql)
|
|
63
|
+
while i < n:
|
|
64
|
+
ch = sql[i]
|
|
65
|
+
if ch in ("'", '"', "`"):
|
|
66
|
+
quote = ch
|
|
67
|
+
out.append(" ")
|
|
68
|
+
i += 1
|
|
69
|
+
while i < n:
|
|
70
|
+
if sql[i] == quote:
|
|
71
|
+
# Doubled quote = escaped quote inside the literal.
|
|
72
|
+
if i + 1 < n and sql[i + 1] == quote:
|
|
73
|
+
out.append(" ")
|
|
74
|
+
i += 2
|
|
75
|
+
continue
|
|
76
|
+
out.append(" ")
|
|
77
|
+
i += 1
|
|
78
|
+
break
|
|
79
|
+
out.append(" " if sql[i] != "\n" else "\n")
|
|
80
|
+
i += 1
|
|
81
|
+
elif ch == "[":
|
|
82
|
+
# T-SQL bracketed identifier.
|
|
83
|
+
out.append(" ")
|
|
84
|
+
i += 1
|
|
85
|
+
while i < n and sql[i] != "]":
|
|
86
|
+
out.append(" ")
|
|
87
|
+
i += 1
|
|
88
|
+
if i < n:
|
|
89
|
+
out.append(" ")
|
|
90
|
+
i += 1
|
|
91
|
+
elif ch == "-" and sql[i : i + 2] == "--":
|
|
92
|
+
while i < n and sql[i] != "\n":
|
|
93
|
+
out.append(" ")
|
|
94
|
+
i += 1
|
|
95
|
+
elif ch == "/" and sql[i : i + 2] == "/*":
|
|
96
|
+
out.append(" ")
|
|
97
|
+
i += 2
|
|
98
|
+
while i < n and sql[i : i + 2] != "*/":
|
|
99
|
+
out.append(" " if sql[i] != "\n" else "\n")
|
|
100
|
+
i += 1
|
|
101
|
+
if i < n:
|
|
102
|
+
out.append(" ")
|
|
103
|
+
i += 2
|
|
104
|
+
else:
|
|
105
|
+
out.append(ch)
|
|
106
|
+
i += 1
|
|
107
|
+
return "".join(out)
|
|
108
|
+
|
|
109
|
+
|
|
110
|
+
def assert_single_statement(sql: str) -> str:
|
|
111
|
+
"""Reject payloads containing more than one SQL statement.
|
|
112
|
+
|
|
113
|
+
Returns the stripped (literal/comment-free) text for further inspection.
|
|
114
|
+
"""
|
|
115
|
+
stripped = strip_literals_and_comments(sql)
|
|
116
|
+
head, sep, tail = stripped.partition(";")
|
|
117
|
+
if sep and tail.strip():
|
|
118
|
+
raise StatementNotAllowedError(
|
|
119
|
+
"Multiple SQL statements in one call are not allowed; "
|
|
120
|
+
"send one statement per call (sql_execute action 'script' runs "
|
|
121
|
+
"a list of statements in a single transaction)."
|
|
122
|
+
)
|
|
123
|
+
if not head.strip():
|
|
124
|
+
raise StatementNotAllowedError("Empty SQL statement.")
|
|
125
|
+
return stripped
|
|
126
|
+
|
|
127
|
+
|
|
128
|
+
def first_keyword(stripped_sql: str) -> str:
|
|
129
|
+
"""Return the first significant keyword of a stripped statement."""
|
|
130
|
+
for match in _TOKEN_RE.finditer(stripped_sql):
|
|
131
|
+
tok = match.group(0)
|
|
132
|
+
if tok in ("(", ")", ";"):
|
|
133
|
+
continue
|
|
134
|
+
return tok.lower()
|
|
135
|
+
return ""
|
|
136
|
+
|
|
137
|
+
|
|
138
|
+
def assert_read_only(sql: str) -> None:
|
|
139
|
+
"""Raise :class:`StatementNotAllowedError` unless ``sql`` is a read.
|
|
140
|
+
|
|
141
|
+
Checks, in order: single statement, allowlisted first keyword, no
|
|
142
|
+
depth-zero mutating keyword inside a CTE, and no depth-zero ``INTO``
|
|
143
|
+
(``SELECT INTO`` / ``INTO OUTFILE`` are writes).
|
|
144
|
+
"""
|
|
145
|
+
stripped = assert_single_statement(sql)
|
|
146
|
+
keyword = first_keyword(stripped)
|
|
147
|
+
if keyword not in READ_ONLY_STARTERS:
|
|
148
|
+
allowed = ", ".join(sorted(k.upper() for k in READ_ONLY_STARTERS))
|
|
149
|
+
raise StatementNotAllowedError(
|
|
150
|
+
f"Statement type {keyword.upper()!r} is not allowed by sql_query "
|
|
151
|
+
f"(read-only). Allowed: {allowed}. Use sql_execute for writes "
|
|
152
|
+
"(requires SQL_ALLOW_WRITES=True on the server)."
|
|
153
|
+
)
|
|
154
|
+
|
|
155
|
+
depth = 0
|
|
156
|
+
for match in _TOKEN_RE.finditer(stripped):
|
|
157
|
+
tok = match.group(0)
|
|
158
|
+
if tok == "(":
|
|
159
|
+
depth += 1
|
|
160
|
+
elif tok == ")":
|
|
161
|
+
depth = max(0, depth - 1)
|
|
162
|
+
elif depth == 0:
|
|
163
|
+
lowered = tok.lower()
|
|
164
|
+
if lowered in MUTATING_KEYWORDS:
|
|
165
|
+
raise StatementNotAllowedError(
|
|
166
|
+
f"Top-level {lowered.upper()!r} is not allowed in sql_query "
|
|
167
|
+
"(read-only). Use sql_execute for writes."
|
|
168
|
+
)
|
|
169
|
+
if lowered == "into":
|
|
170
|
+
raise StatementNotAllowedError(
|
|
171
|
+
"Top-level 'INTO' is not allowed in sql_query "
|
|
172
|
+
"(SELECT INTO creates objects). Use sql_execute for writes."
|
|
173
|
+
)
|
|
@@ -0,0 +1,63 @@
|
|
|
1
|
+
#!/usr/bin/python
|
|
2
|
+
"""Pydantic input models for sql-mcp tool parameters (CONCEPT:SQL-1.5).
|
|
3
|
+
|
|
4
|
+
Typed contracts for the ``params_json`` payloads accepted by the four
|
|
5
|
+
action-dispatch MCP tools (``sql_query``, ``sql_execute``, ``sql_schema``,
|
|
6
|
+
``sql_admin``).
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from typing import Any
|
|
10
|
+
|
|
11
|
+
from pydantic import BaseModel, Field
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class QueryInput(BaseModel):
|
|
15
|
+
"""Input model for ``sql_query`` actions (execute / explain)."""
|
|
16
|
+
|
|
17
|
+
sql: str = Field(description="Single read-only statement with :name binds.")
|
|
18
|
+
params: dict[str, Any] | None = Field(
|
|
19
|
+
default=None, description="Bound parameter values."
|
|
20
|
+
)
|
|
21
|
+
max_rows: int | None = Field(
|
|
22
|
+
default=None, description="Row cap (clamped to the server cap)."
|
|
23
|
+
)
|
|
24
|
+
timeout: float | None = Field(
|
|
25
|
+
default=None, description="Statement timeout in seconds."
|
|
26
|
+
)
|
|
27
|
+
|
|
28
|
+
|
|
29
|
+
class ExecuteInput(BaseModel):
|
|
30
|
+
"""Input model for ``sql_execute`` action 'execute' (DML/DDL)."""
|
|
31
|
+
|
|
32
|
+
sql: str = Field(description="Single DML/DDL statement with :name binds.")
|
|
33
|
+
params: dict[str, Any] | list[dict[str, Any]] | None = Field(
|
|
34
|
+
default=None, description="Bound values; a list runs executemany."
|
|
35
|
+
)
|
|
36
|
+
timeout: float | None = Field(
|
|
37
|
+
default=None, description="Statement timeout in seconds."
|
|
38
|
+
)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class ScriptInput(BaseModel):
|
|
42
|
+
"""Input model for ``sql_execute`` action 'script'."""
|
|
43
|
+
|
|
44
|
+
statements: list[str] = Field(
|
|
45
|
+
description="Statements run in one all-or-nothing transaction."
|
|
46
|
+
)
|
|
47
|
+
timeout: float | None = Field(
|
|
48
|
+
default=None, description="Per-statement timeout in seconds."
|
|
49
|
+
)
|
|
50
|
+
|
|
51
|
+
|
|
52
|
+
class SchemaInput(BaseModel):
|
|
53
|
+
"""Input model for ``sql_schema`` actions."""
|
|
54
|
+
|
|
55
|
+
table: str | None = Field(
|
|
56
|
+
default=None, description="Table name (columns/indexes/foreign_keys/ddl)."
|
|
57
|
+
)
|
|
58
|
+
schema_name: str | None = Field(
|
|
59
|
+
default=None, alias="schema", description="Schema/namespace to inspect."
|
|
60
|
+
)
|
|
61
|
+
limit: int | None = Field(
|
|
62
|
+
default=10, description="Row preview limit for the 'sample' action."
|
|
63
|
+
)
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
#!/usr/bin/python
|
|
2
|
+
"""Pydantic response models for sql-mcp result envelopes (CONCEPT:SQL-1.4).
|
|
3
|
+
|
|
4
|
+
Typed contracts for the bounded envelopes returned by the
|
|
5
|
+
:class:`~sql_mcp.api_client.Api` facade and surfaced through the MCP tools.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
from typing import Any
|
|
9
|
+
|
|
10
|
+
from pydantic import BaseModel, Field
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
class QueryResponse(BaseModel):
|
|
14
|
+
"""Bounded result envelope for read-only queries."""
|
|
15
|
+
|
|
16
|
+
columns: list[str] | None = Field(
|
|
17
|
+
default=None, description="Result column names, in select order."
|
|
18
|
+
)
|
|
19
|
+
rows: list[list[Any]] | None = Field(
|
|
20
|
+
default=None, description="Row values (JSON-safe), capped at max_rows."
|
|
21
|
+
)
|
|
22
|
+
row_count: int | None = Field(default=None, description="Number of rows returned.")
|
|
23
|
+
truncated: bool | None = Field(
|
|
24
|
+
default=None, description="True when the row cap cut the result short."
|
|
25
|
+
)
|
|
26
|
+
elapsed_seconds: float | None = Field(
|
|
27
|
+
default=None, description="Wall-clock execution time."
|
|
28
|
+
)
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
class ExecuteResponse(BaseModel):
|
|
32
|
+
"""Result envelope for DML/DDL statements."""
|
|
33
|
+
|
|
34
|
+
affected_rows: int | None = Field(
|
|
35
|
+
default=None, description="Rows affected by the statement."
|
|
36
|
+
)
|
|
37
|
+
elapsed_seconds: float | None = Field(
|
|
38
|
+
default=None, description="Wall-clock execution time."
|
|
39
|
+
)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class PingResponse(BaseModel):
|
|
43
|
+
"""Connection health envelope for ``sql_admin`` action 'ping'."""
|
|
44
|
+
|
|
45
|
+
ok: bool | None = Field(default=None, description="Connection succeeded.")
|
|
46
|
+
latency_seconds: float | None = Field(
|
|
47
|
+
default=None, description="Round-trip latency of SELECT 1."
|
|
48
|
+
)
|
|
49
|
+
raw: dict[str, Any] | None = Field(
|
|
50
|
+
default=None, description="Raw response payload."
|
|
51
|
+
)
|
|
@@ -0,0 +1,242 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: sql-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Generic SQL database (Postgres, MySQL/MariaDB, MSSQL, Oracle, SQLite) API + MCP Server + A2A Server for Agentic AI!
|
|
5
|
+
Author-email: Audel Rouhi <knucklessg1@gmail.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Classifier: Development Status :: 4 - Beta
|
|
8
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
9
|
+
Classifier: Environment :: Console
|
|
10
|
+
Classifier: Operating System :: POSIX :: Linux
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Requires-Python: <3.15,>=3.11
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
License-File: LICENSE
|
|
15
|
+
Requires-Dist: agent-utilities>=0.47.0
|
|
16
|
+
Requires-Dist: python-dotenv>=1.0.0
|
|
17
|
+
Requires-Dist: sqlalchemy>=2.0.0
|
|
18
|
+
Provides-Extra: mcp
|
|
19
|
+
Requires-Dist: agent-utilities[mcp]>=0.47.0; extra == "mcp"
|
|
20
|
+
Provides-Extra: agent
|
|
21
|
+
Requires-Dist: agent-utilities[agent,logfire]>=0.47.0; extra == "agent"
|
|
22
|
+
Provides-Extra: postgres
|
|
23
|
+
Requires-Dist: psycopg[binary]>=3.1.0; extra == "postgres"
|
|
24
|
+
Provides-Extra: mysql
|
|
25
|
+
Requires-Dist: pymysql>=1.1.0; extra == "mysql"
|
|
26
|
+
Provides-Extra: mssql
|
|
27
|
+
Requires-Dist: pyodbc>=5.0.0; extra == "mssql"
|
|
28
|
+
Provides-Extra: oracle
|
|
29
|
+
Requires-Dist: oracledb>=2.0.0; extra == "oracle"
|
|
30
|
+
Provides-Extra: all
|
|
31
|
+
Requires-Dist: sql-mcp[agent,logfire,mcp,mssql,mysql,oracle,postgres]>=0.1.0; extra == "all"
|
|
32
|
+
Provides-Extra: test
|
|
33
|
+
Requires-Dist: pytest-xdist>=3.6.0; extra == "test"
|
|
34
|
+
Requires-Dist: pytest; extra == "test"
|
|
35
|
+
Requires-Dist: pytest-asyncio; extra == "test"
|
|
36
|
+
Requires-Dist: pytest-cov; extra == "test"
|
|
37
|
+
Dynamic: license-file
|
|
38
|
+
|
|
39
|
+
# Sql Mcp
|
|
40
|
+
## API | MCP Server | A2A Agent
|
|
41
|
+
|
|
42
|
+

|
|
43
|
+

|
|
44
|
+

|
|
45
|
+

|
|
46
|
+

|
|
47
|
+

|
|
48
|
+

|
|
49
|
+

|
|
50
|
+

|
|
51
|
+

|
|
52
|
+

|
|
53
|
+

|
|
54
|
+

|
|
55
|
+

|
|
56
|
+

|
|
57
|
+

|
|
58
|
+

|
|
59
|
+
|
|
60
|
+
Generic SQL database **API + MCP Server + A2A Agent** for the agent-utilities
|
|
61
|
+
ecosystem — one connector for **PostgreSQL, MySQL/MariaDB, Microsoft SQL Server,
|
|
62
|
+
Oracle, and SQLite** over SQLAlchemy 2.x Core.
|
|
63
|
+
|
|
64
|
+
*Version: 0.1.0*
|
|
65
|
+
|
|
66
|
+
> **Documentation** — Installation, deployment, and usage across the API, CLI, and
|
|
67
|
+
> MCP interfaces are maintained in [`docs/`](docs/index.md).
|
|
68
|
+
|
|
69
|
+
## Table of Contents
|
|
70
|
+
|
|
71
|
+
- [Overview](#overview)
|
|
72
|
+
- [What it provides](#what-it-provides)
|
|
73
|
+
- [MCP tools](#mcp-tools)
|
|
74
|
+
- [Dialects & extras](#dialects--extras)
|
|
75
|
+
- [Configuration (environment)](#configuration-environment)
|
|
76
|
+
- [Installation](#installation)
|
|
77
|
+
- [Usage](#usage)
|
|
78
|
+
- [MCP config](#mcp-config)
|
|
79
|
+
- [Docker deployment](#docker-deployment)
|
|
80
|
+
- [Safety model](#safety-model)
|
|
81
|
+
- [Tests](#tests)
|
|
82
|
+
|
|
83
|
+
## Overview
|
|
84
|
+
|
|
85
|
+
`sql-mcp` exposes read-only queries, gated DML/DDL, schema reflection, and
|
|
86
|
+
connection administration as typed, deterministic MCP tools, and ships an optional
|
|
87
|
+
Pydantic-AI agent server. It is **read-only by default**: every query passes a
|
|
88
|
+
statement-type allowlist, every result is bounded by a row cap and a timeout, and
|
|
89
|
+
all values travel as bound parameters — never interpolated into SQL strings.
|
|
90
|
+
|
|
91
|
+
## What it provides
|
|
92
|
+
|
|
93
|
+
- **`SqlApi`** (`sql_mcp.api.api_client_sql`) — a SQLAlchemy 2.x Core facade with
|
|
94
|
+
named multi-connection support, lazy engine creation, the read-only statement
|
|
95
|
+
gate, row-cap/timeout enforcement, and bounded result envelopes
|
|
96
|
+
(`{columns, rows, row_count, truncated}`).
|
|
97
|
+
- **Four MCP tools** (`sql-mcp` console script): `sql_query` (execute/explain),
|
|
98
|
+
`sql_execute` (execute/script — gated by `SQL_ALLOW_WRITES`), `sql_schema`
|
|
99
|
+
(schemas/tables/views/columns/indexes/foreign_keys/ddl/sample), and `sql_admin`
|
|
100
|
+
(ping/version/active_connections/connections/dialects). See
|
|
101
|
+
[`docs/usage.md`](docs/usage.md) for the full action surface.
|
|
102
|
+
- **A dialect registry** (`sql_mcp.dialects`) — per-engine driver, URL scheme, pip
|
|
103
|
+
extra, EXPLAIN prefix, and admin SQL. Core ships SQLite only; the other drivers
|
|
104
|
+
install via extras.
|
|
105
|
+
- **An A2A agent server** (`sql-agent` console script) — a Pydantic-AI graph agent
|
|
106
|
+
wired to the MCP server via `MCP_URL`.
|
|
107
|
+
|
|
108
|
+
## MCP tools
|
|
109
|
+
|
|
110
|
+
| Tool | Actions | Description |
|
|
111
|
+
|---|---|---|
|
|
112
|
+
| `sql_query` | `execute`, `explain` | Run a read-only SELECT/CTE with bound parameters, or return the dialect's query plan |
|
|
113
|
+
| `sql_execute` | `execute`, `script` | One DML/DDL statement (or an all-or-nothing statement list) in a transaction — requires `SQL_ALLOW_WRITES=True` |
|
|
114
|
+
| `sql_schema` | `schemas`, `tables`, `views`, `columns`, `indexes`, `foreign_keys`, `ddl`, `sample` | Reflect schemas, tables, columns, indexes, FKs, CREATE DDL, and preview rows |
|
|
115
|
+
| `sql_admin` | `ping`, `version`, `active_connections`, `connections`, `dialects` | Connection health, server version, server sessions, registry info, driver availability |
|
|
116
|
+
|
|
117
|
+
Every tool takes `action`, `params_json`, and an optional `connection` naming one
|
|
118
|
+
of the configured connections. The whole set is toggled with `SQLTOOL`.
|
|
119
|
+
|
|
120
|
+
## Dialects & extras
|
|
121
|
+
|
|
122
|
+
| Dialect | SQLAlchemy scheme | Driver | Install |
|
|
123
|
+
|---|---|---|---|
|
|
124
|
+
| SQLite | `sqlite+pysqlite` | stdlib | `pip install sql-mcp` (core) |
|
|
125
|
+
| PostgreSQL | `postgresql+psycopg` | psycopg 3 | `pip install sql-mcp[postgres]` |
|
|
126
|
+
| MySQL / MariaDB | `mysql+pymysql` | PyMySQL | `pip install sql-mcp[mysql]` |
|
|
127
|
+
| SQL Server | `mssql+pyodbc` | pyodbc | `pip install sql-mcp[mssql]` |
|
|
128
|
+
| Oracle | `oracle+oracledb` | python-oracledb | `pip install sql-mcp[oracle]` |
|
|
129
|
+
|
|
130
|
+
`pip install sql-mcp[all]` pulls every driver plus the MCP and agent extras.
|
|
131
|
+
|
|
132
|
+
## Configuration (environment)
|
|
133
|
+
|
|
134
|
+
| Var | Default | Meaning |
|
|
135
|
+
|---|---|---|
|
|
136
|
+
| `SQL_CONNECTIONS` | _(empty)_ | JSON map of named connections: DSN strings or `{dialect, host, port, username, password, database, options}` objects |
|
|
137
|
+
| `SQL_URL` | _(empty)_ | Single DSN registered as connection `default` |
|
|
138
|
+
| `SQL_DIALECT` / `SQL_HOST` / `SQL_PORT` / `SQL_USERNAME` / `SQL_PASSWORD` / `SQL_DATABASE` / `SQL_OPTIONS` | _(empty)_ | Discrete fields for a single `default` connection |
|
|
139
|
+
| `SQL_ALLOW_WRITES` | `False` | Enable `sql_execute` (DML/DDL). **Read-only by default** |
|
|
140
|
+
| `SQL_MAX_ROWS` | `500` | Per-call row cap; tool requests are clamped to it |
|
|
141
|
+
| `SQL_TIMEOUT_SECONDS` | `30` | Per-statement timeout |
|
|
142
|
+
| `SQLTOOL` | `True` | Register the SQL tool set |
|
|
143
|
+
|
|
144
|
+
With nothing configured the server registers a zero-infra in-memory SQLite
|
|
145
|
+
connection named `memory`, so it works out of the box. Tools take an optional
|
|
146
|
+
`connection` parameter naming one of the configured connections; it defaults to
|
|
147
|
+
the sole/first one. Passwords are parsed into `sqlalchemy.URL` objects and only
|
|
148
|
+
ever rendered redacted. Copy [`.env.example`](.env.example) to `.env` and
|
|
149
|
+
populate only what you use.
|
|
150
|
+
|
|
151
|
+
## Installation
|
|
152
|
+
|
|
153
|
+
```bash
|
|
154
|
+
pip install sql-mcp # core (SQLite, MCP server, API)
|
|
155
|
+
pip install sql-mcp[all] # every driver + MCP + agent extras
|
|
156
|
+
pip install -e . # from source
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
Or pull the container image:
|
|
160
|
+
|
|
161
|
+
```bash
|
|
162
|
+
docker pull knucklessg1/sql-mcp:latest
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
## Usage
|
|
166
|
+
|
|
167
|
+
```bash
|
|
168
|
+
sql-mcp # stdio MCP server (default transport)
|
|
169
|
+
sql-mcp --transport streamable-http --host 0.0.0.0 --port 8000
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Point it at a database:
|
|
173
|
+
|
|
174
|
+
```bash
|
|
175
|
+
export SQL_URL="postgresql+psycopg://svc:****@db.example.com:5432/app"
|
|
176
|
+
sql-mcp
|
|
177
|
+
```
|
|
178
|
+
|
|
179
|
+
Or several:
|
|
180
|
+
|
|
181
|
+
```bash
|
|
182
|
+
export SQL_CONNECTIONS='{
|
|
183
|
+
"warehouse": "postgresql+psycopg://svc:****@dw.example.com:5432/dw",
|
|
184
|
+
"erp": {"dialect": "mysql", "host": "erp.example.com", "username": "svc",
|
|
185
|
+
"password": "****", "database": "erp"}
|
|
186
|
+
}'
|
|
187
|
+
sql-mcp
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
Run the agent server against a live MCP server:
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
sql-agent --mcp-url http://localhost:8000/mcp --host 0.0.0.0 --port 8080
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
## MCP config
|
|
197
|
+
|
|
198
|
+
```json
|
|
199
|
+
{
|
|
200
|
+
"mcpServers": {
|
|
201
|
+
"sql-mcp": {
|
|
202
|
+
"command": "uv",
|
|
203
|
+
"args": ["run", "sql-mcp"],
|
|
204
|
+
"env": {
|
|
205
|
+
"SQL_URL": "postgresql+psycopg://svc:****@db.example.com:5432/app",
|
|
206
|
+
"SQL_ALLOW_WRITES": "False"
|
|
207
|
+
}
|
|
208
|
+
}
|
|
209
|
+
}
|
|
210
|
+
}
|
|
211
|
+
```
|
|
212
|
+
|
|
213
|
+
## Docker deployment
|
|
214
|
+
|
|
215
|
+
```bash
|
|
216
|
+
docker compose -f docker/mcp.compose.yml up -d # MCP server only
|
|
217
|
+
docker compose -f docker/agent.compose.yml up -d # MCP + A2A agent
|
|
218
|
+
curl -s http://localhost:8000/health # {"status":"OK"}
|
|
219
|
+
```
|
|
220
|
+
|
|
221
|
+
Both services read configuration from `../.env` (copy
|
|
222
|
+
[`.env.example`](.env.example)); see [`docs/deployment.md`](docs/deployment.md).
|
|
223
|
+
|
|
224
|
+
## Safety model
|
|
225
|
+
|
|
226
|
+
- **Read-only by default** — `sql_execute` refuses to run unless the *server* was
|
|
227
|
+
started with `SQL_ALLOW_WRITES=True`; agents cannot flip the flag per call.
|
|
228
|
+
- **Statement allowlist** — `sql_query` accepts only `SELECT`/`WITH`/`EXPLAIN`/
|
|
229
|
+
`SHOW`/`DESCRIBE`/`PRAGMA`/`VALUES`; CTEs are inspected at paren depth zero so
|
|
230
|
+
`WITH ... INSERT` cannot smuggle a write, `SELECT INTO` is rejected, and
|
|
231
|
+
multi-statement payloads are refused.
|
|
232
|
+
- **Bounded results** — per-call row caps clamp to `SQL_MAX_ROWS`; statements run
|
|
233
|
+
under `SQL_TIMEOUT_SECONDS` on a worker thread.
|
|
234
|
+
- **Parameterized only** — values bind via `:name` parameters; identifiers are
|
|
235
|
+
quoted by SQLAlchemy reflection, never hand-interpolated.
|
|
236
|
+
|
|
237
|
+
## Tests
|
|
238
|
+
|
|
239
|
+
```bash
|
|
240
|
+
python -m pytest # full suite against in-memory SQLite (no live DBs)
|
|
241
|
+
pre-commit run --all-files
|
|
242
|
+
```
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
sql_mcp/__init__.py,sha256=UKk2kQcTfuziAS-zLROroHvh-hE_CwhrKGKg2nLDE8w,1969
|
|
2
|
+
sql_mcp/__main__.py,sha256=zTRw8hiXzH7JYZXbXIU82pPTwE79CTdY0yeDd_unPvo,93
|
|
3
|
+
sql_mcp/agent_server.py,sha256=4hNLUgwEyBDk_DvHzVN1sfWt7WEssuUoO8Tnt4Weyy0,2246
|
|
4
|
+
sql_mcp/api_client.py,sha256=ecO-M6gqFR4fbQurXbGzGmcnN4XIL8X7udXeyeyrlJ4,216
|
|
5
|
+
sql_mcp/auth.py,sha256=Bd8MhGyWD7nOTq4WmEAd7-R1LVC6kj5TtO5dwzOGeVE,4907
|
|
6
|
+
sql_mcp/dialects.py,sha256=_yTIqRqdOwjBrJVLg53j2M1JuporDPpjGbugUYu3KK8,5796
|
|
7
|
+
sql_mcp/main_agent.json,sha256=3IQ-xaWgPF_3FNCxTXUUbZTvPYZ86YlAXuyVRvUeKnE,761
|
|
8
|
+
sql_mcp/mcp_config.json,sha256=cNNBmPPOMlHq8Qy7dNuOqIPf11ksjldHxrmXBBypl04,1024
|
|
9
|
+
sql_mcp/mcp_server.py,sha256=FkWsa7iC5A0-VdnSWPjWbu5cPjRlbJB-qJ245j6gSFk,1850
|
|
10
|
+
sql_mcp/safety.py,sha256=8C_sZkqBedDyrmmQKAP342VXQQoIaUIR0fgY7cyzXo8,5527
|
|
11
|
+
sql_mcp/sql_input_models.py,sha256=8BRrWicjQeNEC6mVQsFsy64JJuyPdeTxmKf2cvivuHc,2024
|
|
12
|
+
sql_mcp/sql_response_models.py,sha256=lEoXfUnAgyTAEVe4hW03YB4xPPMIIidRuvIqKaxKCFc,1673
|
|
13
|
+
sql_mcp/api/__init__.py,sha256=l6AnvVhbuZwNKTvNBBTyRYCh-LbqCjdo1Uv72Qu8rHw,197
|
|
14
|
+
sql_mcp/api/api_client_sql.py,sha256=1hHr6WC18EZVEc1CrdEeg1rbGCCBzz7QAnFv_Ou5n1s,18504
|
|
15
|
+
sql_mcp/mcp/__init__.py,sha256=LtlFYBHC_ic-cBeut2eK0mtUhWEbHQCmGt1yPa94qXk,127
|
|
16
|
+
sql_mcp/mcp/mcp_sql.py,sha256=G8L3cBNifgAop93mrphXBUjWC4YZ8CvlKcXeLgwaZsk,8942
|
|
17
|
+
sql_mcp-0.1.0.dist-info/licenses/LICENSE,sha256=jF72OTufeQjenEQ8LJ_eSx7TAyClBHShwYcqjiTLrss,1070
|
|
18
|
+
sql_mcp-0.1.0.dist-info/METADATA,sha256=MuoaV-DoH54msglRACtEoL_ggLfkQ_gzXWnLpqZRuEc,10037
|
|
19
|
+
sql_mcp-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
|
|
20
|
+
sql_mcp-0.1.0.dist-info/entry_points.txt,sha256=2fm-CH-KJ9_uLt5Nnqw7_y89Jw0TcpE8g1GtmVlrz8I,104
|
|
21
|
+
sql_mcp-0.1.0.dist-info/top_level.txt,sha256=8obmI-aU_EX11fzddBJK87KRYU3jQaaOzIi2VHAsMMs,8
|
|
22
|
+
sql_mcp-0.1.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Knuckles-Team
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
sql_mcp
|