Py Mcp Mssql

What is Py Mcp Mssql about?

A Python‑based MCP server that connects to Microsoft SQL Server, exposing table schemas and query execution as FastAPI endpoints. It allows language models (e.g., Claude, ChatGPT) to retrieve metadata, read sample data, and run arbitrary SQL statements in a controlled, asynchronous environment.

How to use Py Mcp Mssql?

1. Clone & install

   git clone https://github.com/amornpan/py-mcp-mssql.git
   cd py-mcp-mssql
   pip install -r requirements.txt
   

2. Configure – create a .env file (or copy .env.example) with your MSSQL credentials:

   MSSQL_SERVER=your_server
   MSSQL_DATABASE=your_database
   MSSQL_USER=your_username
   MSSQL_PASSWORD=your_password
   MSSQL_DRIVER={ODBC Driver 17 for SQL Server}
   

3. Run the server

   python src/mssql/server.py
   

   The server starts a FastAPI service (default http://127.0.0.1:8000).
4. Integrate – add the server definition to Claude Desktop or any MCP‑compatible client as shown in the README.

Key features of Py Mcp Mssql

• Fully asynchronous using asyncio.
• Environment‑driven configuration via python-dotenv.
• Connection pooling with pyodbc and ODBC Driver 17.
• Automatic schema discovery and URI‑based resource listing.
• CSV‑formatted data preview (first 100 rows) for quick inspection.
• Execution of SELECT and data‑modifying statements with result handling.
• Comprehensive logging and error handling.
• Pydantic models ensure input validation and type safety.
• Simple FastAPI integration for extensibility.

Use cases of Py Mcp Mssql

Scenario	Benefit
LLM‑driven data analysis	Language models can query live MSSQL data without custom code.
Chat‑assistant database access	Provides a secure, standardized endpoint for chat bots to fetch or modify records.
Rapid prototyping	Developers can spin up a MCP server to expose existing databases to AI agents in minutes.
Data validation pipelines	Automated tools can call the server to validate schema constraints before ETL jobs.

FAQ from the Py Mcp Mssql

• Do I need to install the ODBC driver manually? Yes, install ODBC Driver 17 for SQL Server on the host machine before running the server.
• Can I limit the rows returned? The server automatically caps CSV previews at 100 rows; you can modify server.py to change this limit.
• What happens if a query fails? Errors are logged and returned in the MCP response with a descriptive message.
• Is authentication handled securely? Credentials are loaded from environment variables; avoid committing .env to version control.
• Which Python versions are supported? Python 3.8 and newer.

Python MSSQL MCP Server

A Model Context Protocol server implementation in Python that provides access to Microsoft SQL Server databases. This server enables Language Models to inspect table schemas and execute SQL queries through a standardized interface.

Features

Core Functionality

• Asynchronous operation using Python's asyncio
• Environment-based configuration using python-dotenv
• Comprehensive logging system
• Connection pooling and management via pyodbc
• Error handling and recovery
• FastAPI integration for API endpoints
• Pydantic models for data validation
• MSSQL connection handling with ODBC Driver

Prerequisites

• Python 3.x
• Required Python packages:
  • pyodbc
  • pydantic
  • python-dotenv
  • mcp-server
• ODBC Driver 17 for SQL Server

Installation

git clone https://github.com/amornpan/py-mcp-mssql.git
cd py-mcp-mssql
pip install -r requirements.txt

Screenshots

The screenshot above demonstrates the server being used with Claude to analyze and visualize SQL data.

Project Structure

PY-MCP-MSSQL/
├── src/
│   └── mssql/
│       ├── __init__.py
│       └── server.py
├── tests/
│   ├── __init__.py
│   ├── test_mssql.py
│   └── test_packages.py
├── .env
├── .env.example
├── .gitignore
├── README.md
└── requirements.txt

Directory Structure Explanation

• src/mssql/ - Main source code directory
  • __init__.py - Package initialization
  • server.py - Main server implementation
• tests/ - Test files directory
  • __init__.py - Test package initialization
  • test_mssql.py - MSSQL functionality tests
  • test_packages.py - Package dependency tests
• .env - Environment configuration file (not in git)
• .env.example - Example environment configuration
• .gitignore - Git ignore rules
• README.md - Project documentation
• requirements.txt - Project dependencies

Configuration

Create a .env file in the project root:

MSSQL_SERVER=your_server
MSSQL_DATABASE=your_database
MSSQL_USER=your_username
MSSQL_PASSWORD=your_password
MSSQL_DRIVER={ODBC Driver 17 for SQL Server}

API Implementation Details

Resource Listing

@app.list_resources()
async def list_resources() -> list[Resource]

• Lists all available tables in the database
• Returns table names with URIs in the format mssql://<table_name>/data
• Includes table descriptions and MIME types

Resource Reading

@app.read_resource()
async def read_resource(uri: AnyUrl) -> str

• Reads data from specified table
• Accepts URIs in the format mssql://<table_name>/data
• Returns first 100 rows in CSV format
• Includes column headers

SQL Execution

@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[TextContent]

• Executes SQL queries
• Supports both SELECT and modification queries
• Returns results in CSV format for SELECT queries
• Returns affected row count for modification queries

Usage with Claude Desktop

Add to your Claude Desktop configuration:

On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "mssql": {
      "command": "python",
      "args": [
        "server.py"
      ],
      "env": {
        "MSSQL_SERVER": "your_server",
        "MSSQL_DATABASE": "your_database",
        "MSSQL_USER": "your_username",
        "MSSQL_PASSWORD": "your_password",
        "MSSQL_DRIVER": "{ODBC Driver 17 for SQL Server}"
      }
    }
  }
}

Error Handling

The server implements comprehensive error handling for:

• Database connection failures
• Invalid SQL queries
• Resource access errors
• URI validation
• Tool execution errors

All errors are logged and returned with appropriate error messages.

Security Features

• Environment variable based configuration
• Connection string security
• Result set size limits
• Input validation through Pydantic
• Proper SQL query handling

Contact Information

Amornpan Phornchaicharoen

Feel free to reach out to me if you have any questions about this project or would like to collaborate!

---

Made with ❤️ by Amornpan Phornchaicharoen

License

This project is licensed under the MIT License - see the LICENSE file for details.

Author

Amornpan Phornchaicharoen

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Requirements

Create a requirements.txt file with:

fastapi>=0.104.1
pydantic>=2.10.6
uvicorn>=0.34.0 
python-dotenv>=1.0.1
pyodbc>=4.0.35
anyio>=4.5.0
mcp==1.2.0

These versions have been tested and verified to work together. The key components are:

• fastapi and uvicorn for the API server
• pydantic for data validation
• pyodbc for SQL Server connectivity
• mcp for Model Context Protocol implementation
• python-dotenv for environment configuration
• anyio for asynchronous I/O support

Acknowledgments

• Microsoft SQL Server team for ODBC drivers
• Python pyodbc maintainers
• Model Context Protocol community
• Contributors to the python-dotenv project