sql-mcp-server 0.1.0__py3-none-any.whl

db.py

@@ -0,0 +1,27 @@
+import pyodbc
+import os
+from dotenv import load_dotenv
+from pathlib import Path
+
+# Force load .env from the project folder
+load_dotenv(dotenv_path=Path(__file__).parent / ".env")
+
+# db.py — support both auth modes
+def get_connection():
+    driver = os.getenv("DB_DRIVER", "ODBC Driver 17 for SQL Server")
+    server = os.getenv("DB_SERVER")
+    database = os.getenv("DB_NAME")
+    username = os.getenv("DB_USER")   # new
+    password = os.getenv("DB_PASSWORD")  # new
+
+    if username and password:
+        conn_str = (
+            f"DRIVER={{{driver}}};SERVER={server};DATABASE={database};"
+            f"UID={username};PWD={password};TrustServerCertificate=yes;"
+        )
+    else:
+        conn_str = (
+            f"DRIVER={{{driver}}};SERVER={server};DATABASE={database};"
+            "Trusted_Connection=yes;TrustServerCertificate=yes;"
+        )
+    return pyodbc.connect(conn_str)

server.py

@@ -0,0 +1,229 @@
+from mcp.server.fastmcp import FastMCP
+from db import get_connection
+import json
+import re
+
+# Initialize FastMCP server
+mcp = FastMCP("sql-assistant")
+
+# ─────────────────────────────────────────────
+# Helpers
+# ─────────────────────────────────────────────
+FORBIDDEN_KEYWORDS = ["INSERT", "UPDATE", "DELETE", "DROP", "TRUNCATE", "ALTER", "CREATE", "EXEC"]
+
+def _check_select_only(sql: str) -> str | None:
+    """Return an error message if `sql` contains a forbidden keyword, else None."""
+    sql_upper = sql.strip().upper()
+    for keyword in FORBIDDEN_KEYWORDS:
+        if sql_upper.startswith(keyword) or f" {keyword} " in sql_upper:
+            return f"❌ '{keyword}' statements are not allowed. Only SELECT queries are permitted."
+    return None
+
+def _validate_identifier(name: str) -> bool:
+    """Return True if `name` is a safe SQL identifier (letters, digits, underscores)."""
+    return bool(re.match(r'^[a-zA-Z0-9_]+$', name))
+
+
+# ─────────────────────────────────────────────
+# TOOL 1: list_tables
+# ─────────────────────────────────────────────
+@mcp.tool()
+def list_tables() -> str:
+    """
+    List all user-created tables in the connected MS SQL database.
+    Returns table names along with their schema.
+    """
+    query = """
+        SELECT TABLE_SCHEMA, TABLE_NAME
+        FROM INFORMATION_SCHEMA.TABLES
+        WHERE TABLE_TYPE = 'BASE TABLE'
+        ORDER BY TABLE_SCHEMA, TABLE_NAME
+    """
+    try:
+        conn = get_connection()
+        cursor = conn.cursor()
+        cursor.execute(query)
+        rows = cursor.fetchall()
+        conn.close()
+
+        if not rows:
+            return "No tables found in the database."
+
+        result = "Tables in database:\n\n"
+        for schema, table in rows:
+            result += f"  [{schema}].[{table}]\n"
+        return result
+
+    except Exception as e:
+        return f"Error fetching tables: {str(e)}"
+
+
+# ─────────────────────────────────────────────
+# TOOL 2: describe_table
+# ─────────────────────────────────────────────
+@mcp.tool()
+def describe_table(table_name: str, schema: str = "dbo") -> str:
+    """
+    Describe the structure of a specific table — columns, data types, nullability.
+
+    Args:
+        table_name: Name of the table (e.g. Customers)
+        schema: Schema name, default is 'dbo'
+    """
+    query = """
+        SELECT 
+            COLUMN_NAME,
+            DATA_TYPE,
+            CHARACTER_MAXIMUM_LENGTH,
+            IS_NULLABLE,
+            COLUMN_DEFAULT
+        FROM INFORMATION_SCHEMA.COLUMNS
+        WHERE TABLE_NAME = ? AND TABLE_SCHEMA = ?
+        ORDER BY ORDINAL_POSITION
+    """
+    try:
+        conn = get_connection()
+        cursor = conn.cursor()
+        cursor.execute(query, (table_name, schema))
+        rows = cursor.fetchall()
+        conn.close()
+
+        if not rows:
+            return f"Table [{schema}].[{table_name}] not found or has no columns."
+
+        result = f"Structure of [{schema}].[{table_name}]:\n\n"
+
+        for col_name, data_type, max_len, nullable, default in rows:
+            max_len = max_len if max_len else "-"
+            default = default if default else "-"
+            
+            result += f"{col_name} | {data_type} | {max_len} | {nullable} | {default}\n"
+
+        return result
+
+    except Exception as e:
+        return f"Error describing table: {str(e)}"
+
+
+# ─────────────────────────────────────────────
+# TOOL 3: run_query
+# ─────────────────────────────────────────────
+@mcp.tool()
+def run_query(sql: str, max_rows: int = 50) -> str:
+    """
+    Run a SELECT SQL query on the MS SQL database and return results.
+    Only SELECT statements are allowed for safety.
+
+    Args:
+        sql: A valid T-SQL SELECT query
+        max_rows: Maximum rows to return (default 50, max 200)
+    """
+    # Safety check — block destructive statements
+    err = _check_select_only(sql)
+    if err:
+        return err
+
+    max_rows = min(max_rows, 200)  # hard cap
+
+    try:
+        conn = get_connection()
+        cursor = conn.cursor()
+        cursor.execute(sql)
+        rows = cursor.fetchmany(max_rows)
+        columns = [desc[0] for desc in cursor.description]
+        conn.close()
+
+        if not rows:
+            return "Query executed successfully. No rows returned."
+
+        # Format as a readable table
+        col_widths = [max(len(str(col)), max((len(str(row[i])) for row in rows), default=0)) for i, col in enumerate(columns)]
+
+        header = " | ".join(str(col).ljust(col_widths[i]) for i, col in enumerate(columns))
+        separator = "-+-".join("-" * w for w in col_widths)
+        result_lines = [header, separator]
+
+        for row in rows:
+            line = " | ".join(str(val).ljust(col_widths[i]) for i, val in enumerate(row))
+            result_lines.append(line)
+
+        result_lines.append(f"\n({len(rows)} rows returned)")
+        return "\n".join(result_lines)
+
+    except Exception as e:
+        return f"Query error: {str(e)}"
+
+
+# ─────────────────────────────────────────────
+# TOOL 4: explain_query
+# ─────────────────────────────────────────────
+@mcp.tool()
+def explain_query(sql: str) -> str:
+    """
+    Show the estimated execution plan for a SELECT query using SET SHOWPLAN_TEXT.
+    Helps understand how SQL Server processes the query.
+
+    Args:
+        sql: A valid T-SQL SELECT query to explain
+    """
+    # Safety check — same rules as run_query
+    err = _check_select_only(sql)
+    if err:
+        return err
+
+    conn = None
+    try:
+        conn = get_connection()
+        cursor = conn.cursor()
+
+        cursor.execute("SET SHOWPLAN_TEXT ON")
+        cursor.execute(sql)
+        rows = cursor.fetchall()
+
+        if not rows:
+            return "No execution plan returned."
+
+        plan_lines = [str(row[0]) for row in rows]
+        return "Execution Plan:\n\n" + "\n".join(plan_lines)
+
+    except Exception as e:
+        return f"Error fetching execution plan: {str(e)}"
+    finally:
+        if conn:
+            try:
+                conn.cursor().execute("SET SHOWPLAN_TEXT OFF")
+            except Exception:
+                pass
+            conn.close()
+
+
+# ─────────────────────────────────────────────
+# TOOL 5: get_table_sample
+# ─────────────────────────────────────────────
+@mcp.tool()
+def get_table_sample(table_name: str, schema: str = "dbo", rows: int = 5) -> str:
+    """
+    Preview the first N rows of any table quickly.
+
+    Args:
+        table_name: Name of the table
+        schema: Schema name, default is 'dbo'
+        rows: Number of rows to preview (default 5)
+    """
+    if not _validate_identifier(table_name):
+        return f"❌ Invalid table name: '{table_name}'. Only letters, digits, and underscores are allowed."
+    if not _validate_identifier(schema):
+        return f"❌ Invalid schema name: '{schema}'. Only letters, digits, and underscores are allowed."
+
+    sql = f"SELECT TOP {min(rows, 20)} * FROM [{schema}].[{table_name}]"
+    return run_query(sql)
+
+
+# ─────────────────────────────────────────────
+# Entry Point
+# ─────────────────────────────────────────────
+def main():
+    mcp.run(transport="stdio")
+
+if __name__ == "__main__":
+    main()

sql_mcp_server-0.1.0.dist-info/METADATA

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: sql-mcp-server
+Version: 0.1.0
+Summary: MCP server that connects Claude to a Microsoft SQL Server database
+Author: Snehangshu
+License: MIT
+License-File: LICENSE
+Keywords: ai,claude,database,mcp,sql-server
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Requires-Python: >=3.12
+Requires-Dist: mcp[cli]>=1.26.0
+Requires-Dist: pyodbc>=5.3.0
+Requires-Dist: python-dotenv>=1.2.2
+Description-Content-Type: text/markdown
+
+# SQL Assistant MCP Server
+
+An MCP server that connects Claude to a Microsoft SQL Server database over stdio. Ask Claude to query your database, check table structures, or see how a query runs — without leaving the chat window.
+
+---
+
+## Installation
+
+```bash
+pip install sql-mcp-server
+```
+
+You also need the **ODBC Driver for SQL Server** installed:
+https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server
+
+---
+
+## Tools
+
+**list_tables** — Lists every user-created table in the database, grouped by schema.
+
+**describe_table** — Shows columns, data types, nullability, and defaults for a table.
+
+**run_query** — Runs a SELECT query and returns results. Write operations (INSERT, UPDATE, DELETE, DROP, etc.) are blocked.
+
+**explain_query** — Returns SQL Server's estimated execution plan via `SET SHOWPLAN_TEXT`. Useful before running a slow or unfamiliar query.
+
+**get_table_sample** — Returns the first N rows (up to 20) from a table. Default is 5 — pass `rows=10` for more.
+
+---
+
+## Project structure
+```
+sql-mcp-server/
+├── server.py          # MCP server and tool definitions
+├── db.py              # SQL Server connection helper (loads .env)
+├── pyproject.toml     # Project metadata and dependencies
+├── uv.lock            # Locked dependency versions (uv)
+├── .env               # Connection config (not committed)
+└── README.md         
+```
+
+---
+
+## Setup
+
+### 1. Configure the database connection
+
+Create a `.env` file in the project root:
+
+**Windows Authentication (Trusted Connection):**
+```env
+DB_DRIVER=ODBC Driver 17 for SQL Server
+DB_SERVER=YOUR_SERVER_NAME\\SQLEXPRESS
+DB_NAME=your_database_name
+```
+
+**SQL Server Authentication (username + password):**
+```env
+DB_DRIVER=ODBC Driver 17 for SQL Server
+DB_SERVER=YOUR_SERVER_NAME\\SQLEXPRESS
+DB_NAME=your_database_name
+DB_USER=your_username
+DB_PASSWORD=your_password
+```
+
+If you're using the Claude Desktop config below, put your credentials in the `env` block — no `.env` file needed.
+
+---
+
+### 2. Register with Claude Desktop
+
+Add this to `claude_desktop_config.json`:
+
+**Windows Authentication:**
+```json
+{
+  "mcpServers": {
+    "sql-assistant": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "C:/path/to/sql-mcp-server",
+        "run",
+        "server.py"
+      ],
+      "env": {
+        "DB_SERVER": "YOUR_SERVER_NAME\\\\SQLEXPRESS",
+        "DB_NAME": "your_database_name",
+        "DB_DRIVER": "ODBC Driver 17 for SQL Server"
+      }
+    }
+  }
+}
+```
+
+**SQL Server Authentication:**
+```json
+{
+  "mcpServers": {
+    "sql-assistant": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "C:/path/to/sql-mcp-server",
+        "run",
+        "server.py"
+      ],
+      "env": {
+        "DB_SERVER": "YOUR_SERVER_NAME\\\\SQLEXPRESS",
+        "DB_NAME": "your_database_name",
+        "DB_DRIVER": "ODBC Driver 17 for SQL Server",
+        "DB_USER": "your_username",
+        "DB_PASSWORD": "your_password"
+      }
+    }
+  }
+}
+```
+
+Replace the placeholder values with your actual details. Restart Claude Desktop after saving.
+
+---
+
+## Usage
+
+With the server running, try asking Claude:
+
+- "What tables are in the database?"
+- "Describe the Orders table."
+- "Show me 10 rows from Customers."
+- "Run: SELECT TOP 5 * FROM Sales.Orders WHERE Status = 'Pending'"
+- "Explain this query: SELECT * FROM Products WHERE Price > 100"
+
+---
+
+## Safety
+
+Only SELECT queries run. These keywords are blocked before they reach the database:
+
+`INSERT` `UPDATE` `DELETE` `DROP` `TRUNCATE` `ALTER` `CREATE` `EXEC`
+
+Table and schema names are validated against injection patterns. Results cap at 200 rows.
+
+> ⚠️ **Don't commit your `.env` file** — it contains your connection credentials.
+
+---
+
+## Requirements
+
+- Python 3.12+
+- SQL Server with ODBC Driver 17 or 18
+- Claude Desktop with MCP support
+
+---
+
+## License
+
+MIT

sql_mcp_server-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+db.py,sha256=4qP9HX4IDamu7zqxSMiCQG_zOCPbIGFtNkrE68uXVio,916
+server.py,sha256=JC9wI6WJ4ZzxUCal69WrNBOr_uvbt_740_Fxakwr_eM,8578
+sql_mcp_server-0.1.0.dist-info/METADATA,sha256=HAsMJ-fsfi90eNxitTHQWv3lOv1qpGF_h2g6y4f4gGU,4557
+sql_mcp_server-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sql_mcp_server-0.1.0.dist-info/entry_points.txt,sha256=GJySdKWFd3S7nJoNcbECz1Nz8teN-aJBrJH9AbIySgM,47
+sql_mcp_server-0.1.0.dist-info/licenses/LICENSE,sha256=EbNPKITs5IpzocH7nlUejIW62m8GMwcQa7Atd_4nUWU,1094
+sql_mcp_server-0.1.0.dist-info/RECORD,,

sql_mcp_server-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

sql_mcp_server-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+sql-mcp-server = server:main

sql_mcp_server-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Snehangshu Bhuin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.