Skip to content

installation.md

Latest commit

 

History

History
329 lines (250 loc) · 8.15 KB

installation.md

File metadata and controls

329 lines (250 loc) · 8.15 KB
Raw

Installation Guide

This guide covers installing pymssql-mcp and configuring it to work with Claude Desktop.

New to MCP? Start with What is MCP? to understand how this all works.

Want the fastest path? See the Quickstart Guide for a 10-minute setup.

What Gets Installed

When you install pymssql-mcp, you get:

  • pymssql-mcp - The MCP server that connects Claude to SQL Server
  • pymssql - Python driver for SQL Server connectivity
  • FastMCP - The framework for building MCP servers
  • Supporting libraries - pydantic-settings, starlette (for HTTP mode)

The installation is about 30MB total.

Prerequisites

Before installing, you need:

Requirement Why You Need It How to Get It
Python 3.10+ Runs the MCP server python.org/downloads
Claude Desktop The AI assistant that uses MCP claude.ai/download
SQL Server access The database you're connecting to Contact your DBA

Checking Python Version

python --version
# Should show Python 3.10.x or higher

If you see Python 2.x or an older 3.x version, install a newer Python first.

SQL Server Requirements

You'll need:

  • SQL Server hostname or IP address
  • Username and password with database access
  • Database name to connect to
  • Network access from your computer (port 1433 by default)

Installation Methods

Method 1: pip (Recommended)

pip install pymssql-mcp

Method 2: uvx (Isolated Execution)

uvx pymssql-mcp

This runs pymssql-mcp in an isolated environment without permanent installation.

Method 3: From Source

git clone https://github.com/bpamiri/pymssql-mcp.git
cd pymssql-mcp
pip install -e .

Claude Desktop Setup

Claude Desktop needs to know about pymssql-mcp so it can start it and communicate with it. This is done through a JSON configuration file.

Understanding the Config File

The config file tells Claude Desktop:

  • Where to find pymssql-mcp (the command field)
  • How to connect to your database (the env field with credentials)
  • What to call this server (the key name, like "mssql")

When Claude Desktop starts, it reads this config and launches pymssql-mcp in the background.

1. Locate the Config File

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

2. Add pymssql-mcp Configuration

Create or edit the config file. Here's what each part means:

{
  "mcpServers": {
    "mssql": {
      "command": "uvx",
      "args": ["pymssql-mcp"],
      "env": {
        "MSSQL_HOST": "your-server.example.com",
        "MSSQL_USER": "username",
        "MSSQL_PASSWORD": "password",
        "MSSQL_DATABASE": "YourDatabase"
      }
    }
  }
}

Config breakdown:

Field Purpose Example
"mssql" Name for this server (you choose) "mssql" or "production-db"
command Program to run "uvx" or "pymssql-mcp"
args Command arguments ["pymssql-mcp"] for uvx
MSSQL_HOST Database server hostname "sqlserver.company.com"
MSSQL_USER Database username "appuser"
MSSQL_PASSWORD Database password "secretpassword"
MSSQL_DATABASE Database name "SalesDB"

3. Alternative: Using pip Installation

If you installed via pip:

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

4. Alternative: From Source with Virtual Environment

If running from source:

{
  "mcpServers": {
    "mssql": {
      "command": "/bin/bash",
      "args": ["-c", "cd /path/to/pymssql-mcp && .venv/bin/python -m mssql_mcp"],
      "env": {
        "MSSQL_HOST": "your-server.example.com",
        "MSSQL_USER": "username",
        "MSSQL_PASSWORD": "password",
        "MSSQL_DATABASE": "YourDatabase"
      }
    }
  }
}

5. Restart Claude Desktop

Quit Claude Desktop completely (Cmd+Q on macOS, or exit from system tray on Windows) and reopen it.

6. Verify Installation

In Claude Desktop, you should see a hammer icon indicating tools are available. Try asking:

"Connect to the database and list available tables"

Optional Settings

Add these to your env section for additional control:

{
  "mcpServers": {
    "mssql": {
      "command": "pymssql-mcp",
      "env": {
        "MSSQL_HOST": "your-server.example.com",
        "MSSQL_USER": "username",
        "MSSQL_PASSWORD": "password",
        "MSSQL_DATABASE": "YourDatabase",
        "MSSQL_PORT": "1433",
        "MSSQL_READ_ONLY": "true",
        "MSSQL_MAX_ROWS": "1000"
      }
    }
  }
}
Variable Purpose Default
MSSQL_PORT SQL Server port 1433
MSSQL_READ_ONLY Disable write operations false
MSSQL_MAX_ROWS Limit query results 1000
MSSQL_TIMEOUT Connection timeout (seconds) 30

See Configuration Reference for all options.

Multiple Database Connections

You can configure multiple SQL Server connections:

{
  "mcpServers": {
    "production-db": {
      "command": "pymssql-mcp",
      "env": {
        "MSSQL_HOST": "prod-server.example.com",
        "MSSQL_USER": "readonly_user",
        "MSSQL_PASSWORD": "password",
        "MSSQL_DATABASE": "ProductionDB",
        "MSSQL_READ_ONLY": "true"
      }
    },
    "dev-db": {
      "command": "pymssql-mcp",
      "env": {
        "MSSQL_HOST": "dev-server.example.com",
        "MSSQL_USER": "dev_user",
        "MSSQL_PASSWORD": "password",
        "MSSQL_DATABASE": "DevelopmentDB"
      }
    }
  }
}

Claude will see both as separate tool sets and can work with either.

Azure SQL Database

For Azure SQL Database, use your Azure SQL connection details:

{
  "mcpServers": {
    "azure-sql": {
      "command": "pymssql-mcp",
      "env": {
        "MSSQL_HOST": "your-server.database.windows.net",
        "MSSQL_USER": "your-admin@your-server",
        "MSSQL_PASSWORD": "your-password",
        "MSSQL_DATABASE": "your-database",
        "MSSQL_PORT": "1433"
      }
    }
  }
}

Ensure your Azure SQL firewall allows connections from your IP address.

Troubleshooting

"Module not found" Error

Ensure pymssql-mcp is installed in the Python environment being used:

pip show pymssql-mcp

Connection Refused

  1. Verify your SQL Server is running and accepting connections
  2. Check the hostname and port are correct
  3. Verify network connectivity (try telnet hostname 1433)
  4. Check firewall rules allow the connection
  5. Verify credentials are correct

"Login failed" Error

  1. Verify username and password are correct
  2. Check the database name exists
  3. Ensure the user has permissions on the database
  4. For Windows Authentication issues, use SQL Server Authentication instead

Check MCP Logs

Claude Desktop logs MCP server output to:

macOS:

~/Library/Logs/Claude/mcp-server-mssql.log

Windows:

%APPDATA%\Claude\Logs\mcp-server-mssql.log

Review this file for detailed error messages.

Python Not Found

If Claude can't find Python or pymssql-mcp, use the full path:

{
  "mcpServers": {
    "mssql": {
      "command": "/usr/local/bin/pymssql-mcp",
      "env": { ... }
    }
  }
}

Find your pymssql-mcp path with: which pymssql-mcp (Mac/Linux) or where pymssql-mcp (Windows)

Next Steps

Now that you're installed:

  1. Test the connection - Ask Claude "Connect to the database and show me the current database name"
  2. Explore your data - Ask "What tables are available?"
  3. Learn more: