pyodbc-mcp-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

MSSQL MCP Server - A Model Context Protocol server providing read-only SQL Server access via Windows Authentication. Uses FastMCP for protocol handling and pyodbc for database connectivity.

Development Commands

# Install for development
pip install -e ".[dev]"

# Run tests with coverage
pytest

# Run a single test file
pytest tests/test_server.py

# Run a specific test
pytest tests/test_server.py::TestSecurityFiltering::test_select_query_allowed

# Run the server locally (requires env vars)
python -m mssql_mcp_server

# Format code
black src tests
isort src tests

# Type checking
mypy src

Environment Variables

Variable	Default	Description
MSSQL_SERVER	localhost	SQL Server hostname
MSSQL_DATABASE	master	Target database
ODBC_DRIVER	ODBC Driver 17 for SQL Server	ODBC driver name

⚠️ SECURITY WARNING: Never store sensitive credentials in .env files within the repository directory. Use .env.example as a template and create your local .env file outside the repository, or use GitHub Secrets for CI/CD tokens.

Architecture

Single-File Server Design

The entire MCP server lives in src/mssql_mcp_server/server.py. This file contains:

• Database connection logic using pyodbc with Trusted_Connection=yes
• All five MCP tools decorated with @mcp.tool()
• Security filtering logic for read-only enforcement

MCP Tool Structure

Tools are registered via FastMCP decorator pattern:

mcp = FastMCP("mssql-readonly")

@mcp.tool()
def ToolName(args) -> str:
    # Returns JSON string

Security Model

The ReadData tool implements security at two levels:

1. Query prefix check: Only queries starting with SELECT are allowed
2. Keyword scanning: Blocks dangerous keywords (INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, EXEC, etc.) even in subqueries