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

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

Queries & Schema

CRUD Operations

Stored Procedures

Export & Transactions

Knowledge Persistence

Configuration

Required Variables

Safety Settings

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