pymssql-mcp

An MCP (Model Context Protocol) server for Microsoft SQL Server databases. Enables AI assistants like Claude to interact with SQL Server through a standardized protocol.

Features

• Natural Language Queries: Ask Claude about your data in plain English
• Schema Discovery: Explore tables, views, columns, and relationships
• CRUD Operations: Read, insert, update, and delete rows safely
• Stored Procedures: Execute stored procedures with parameters
• Multi-Database Support: List and switch between databases
• Data Export: Export query results to JSON or CSV files
• Transaction Support: Begin, commit, and rollback transactions
• Knowledge Persistence: Claude remembers what it learns about your database
• Safety Controls: Read-only mode, command blocking, row limits, schema restrictions
• Connection Watchdog: Automatic recovery from hung connections
• OAuth Integration: Deploy as a Claude.ai Custom Connector with SSO

Documentation

Guide	Description
What is MCP?	Understanding MCP and pymssql-mcp
Installation	Complete installation guide
Quickstart	Get running in 10 minutes
Configuration	All configuration options
Tools Reference	Detailed tool documentation
Usage Examples	Common usage patterns
OAuth Setup	Claude.ai integration with SSO

Quick Start

1. Install

pip install pymssql-mcp

2. Configure Claude Desktop

Edit your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mssql": {
      "command": "pymssql-mcp",
      "env": {
        "MSSQL_HOST": "your-server.example.com",
        "MSSQL_USER": "your-username",
        "MSSQL_PASSWORD": "your-password",
        "MSSQL_DATABASE": "your-database",
        "MSSQL_READ_ONLY": "true"
      }
    }
  }
}

3. Restart Claude Desktop

Quit and reopen Claude Desktop. You'll see a hammer icon indicating tools are available.

4. Start Chatting

Ask Claude about your database:

"What tables are available?"

"Describe the Customers table"

"Show me the top 10 orders by total amount"

"How many customers do we have in each state?"

Available Tools

Connection & Database

Tool	Description
connect	Connect to the database
disconnect	Close all connections
list_databases	List available databases
switch_database	Switch database context

Queries & Schema

Tool	Description
execute_query	Run a SELECT query
validate_query	Check if a query is safe
list_tables	List tables and views
describe_table	Get column information

CRUD Operations

Tool	Description
read_rows	Read rows by ID or filter
insert_row	Insert a new row
update_row	Update an existing row
delete_row	Delete a row

Stored Procedures

Tool	Description
list_stored_procs	List available procedures
describe_stored_proc	Get procedure parameters
call_stored_proc	Execute a procedure

Export & Transactions

Tool	Description
export_to_json	Export results to JSON
export_to_csv	Export results to CSV
begin_transaction	Start a transaction
commit_transaction	Commit changes
rollback_transaction	Rollback changes

Knowledge Persistence

Tool	Description
save_knowledge	Save learned information
get_all_knowledge	Retrieve all knowledge
search_knowledge	Search saved knowledge

Configuration

Required Variables

Variable	Description
MSSQL_HOST	SQL Server hostname
MSSQL_USER	Database username
MSSQL_PASSWORD	Database password
MSSQL_DATABASE	Database name

Safety Settings

Variable	Default	Description
MSSQL_READ_ONLY	false	Block all write operations
MSSQL_MAX_ROWS	1000	Maximum rows per query
MSSQL_BLOCKED_COMMANDS	DROP,TRUNCATE,...	Commands to block
MSSQL_ALLOWED_SCHEMAS	(all)	Restrict to specific schemas
MSSQL_BLOCKED_DATABASES	(none)	Hide specific databases

See Configuration Reference for all options.

Deployment Modes

Local (Default)

Run as a local process with Claude Desktop:

pymssql-mcp

HTTP/SSE Server

Run as a shared HTTP server for multiple users:

pymssql-mcp --http --host 0.0.0.0 --port 8080

Streamable HTTP (Claude.ai Integration)

Run with OAuth authentication for Claude.ai:

pymssql-mcp --streamable-http --host 0.0.0.0 --port 8080

See OAuth Setup for complete integration instructions.

Development

# Clone repository
git clone https://github.com/bpamiri/pymssql-mcp.git
cd pymssql-mcp

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

# Run tests
pytest

# Lint and format
ruff check .
ruff format .

# Type check
mypy src/

Security

pymssql-mcp includes multiple safety features:

• Read-only mode: Prevent all write operations
• Command blocking: Block dangerous SQL commands (DROP, TRUNCATE, etc.)
• Schema restrictions: Limit access to specific schemas
• Database blocklist: Hide sensitive databases
• Row limits: Cap query results to prevent memory issues
• Query validation: Analyze queries before execution
• Parameterized queries: Prevent SQL injection

See SECURITY.md for security policy and best practices.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

License

Apache-2.0. See LICENSE for details.

Links

• PyPI Package
• GitHub Repository
• Issue Tracker
• MCP Documentation