MCP-Sql-Server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

MCP SQL Server is a Python MCP (Model Context Protocol) server that exposes SQL Server database inspection and querying capabilities to Claude Desktop and Claude Code. It implements connection pooling, multi-layer SQL injection prevention, schema/table access controls, and the MCP 2026-07-28 spec (Tools, Resources).

Development Commands

# Install in editable mode with dev dependencies
pip install -e ".[dev]"

# Run unit tests (no database required)
pytest tests/ -v

# Run a single test
pytest tests/test_security_validator.py::test_function_name -v

# Lint
ruff check src/

# Format
ruff format src/

# Test connection to a real SQL Server
python test_connection.py

# Start the server manually (blocks waiting for MCP stdio)
python -m mcp_sqlserver.server --connection-string "Driver={ODBC Driver 17 for SQL Server};Server=...;Database=...;Trusted_Connection=yes"

Architecture

Module Layout

src/mcp_sqlserver/
├── server.py       # MCP app instance, list_tools/call_tool handlers, entry point (run/main)
├── config.py       # CLI arg parsing + env var fallback; module-level globals mutated by _load_config()
├── databases.py    # Multi-db registry: Database dataclass (per-db settings + lazy pool), load_databases(), get_database()
├── security.py     # SecurityValidator: is_table_allowed(), validate_query(), extract_table_names()
├── pool.py         # ConnectionPool: thread-safe Queue-based pool with auto-reconnect
├── helpers.py      # Markdown / CSV / JSON result formatting
├── resources.py    # MCP Resources: db://schema/overview, db://schema/tables/{name}, db://dictionary
└── tools/
    ├── __init__.py         # Re-exports all handle_* functions
    ├── list_tables.py
    ├── describe_table.py
    ├── execute_query.py    # includes ensure_top() row-limit injection + per-table access checks
    ├── explain.py          # estimated execution plan (SET SHOWPLAN_ALL)
    ├── relationships.py
    ├── indexes.py
    ├── search_columns.py
    ├── statistics.py
    ├── views.py
    ├── procedures.py
    └── dictionary.py       # update_dictionary tool