Azure SQL Server MCP

A Model Context Protocol (MCP) server that enables Claude Code to execute SQL queries against Azure SQL Database using Azure AD authentication.

Features

• Azure AD Authentication: Uses DefaultAzureCredential for secure authentication
• Three MCP Tools:
  • execute_sql_query: Execute arbitrary SQL queries
  • list_tables: List all tables with schema and row count
  • get_table_schema: Get column details for a specific table
• Connection Pooling: Efficient connection reuse for better performance
• Environment Variable Configuration: Default server and database via environment variables

Prerequisites

• Node.js 18.0.0 or higher
• Azure CLI installed and logged in (for local development)
• Access to an Azure SQL Database

Installation

Add the following configuration to your Claude Code MCP settings (~/.claude/settings.json or project-level .claude/settings.json):

macOS / Linux:

{
  "mcpServers": {
    "azure-sqldb-tools": {
      "command": "npx",
      "args": ["-y", "azure-sqlserver-mcp"],
      "env": {
        "AZURE_SQL_SERVER": "your-server.database.windows.net",
        "AZURE_SQL_DATABASE": "your-database"
      }
    }
  }
}

Windows:

{
  "mcpServers": {
    "azure-sqldb-tools": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "azure-sqlserver-mcp"],
      "env": {
        "AZURE_SQL_SERVER": "your-server.database.windows.net",
        "AZURE_SQL_DATABASE": "your-database"
      }
    }
  }
}

Replace your-server.database.windows.net and your-database with your actual Azure SQL server and database name.

That's it! Claude Code will automatically download and run the package via npm.

Configuration

Environment Variables

| Variable | Description | |----------|-------------| | AZURE_SQL_SERVER | Default Azure SQL server address (e.g., your-server.database.windows.net) | | AZURE_SQL_DATABASE | Default database name |

Tools

execute_sql_query

Execute a SQL query against Azure SQL Database.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | query | string | Yes | The SQL query to execute | | database | string | No | Database name (uses AZURE_SQL_DATABASE if not provided) | | server | string | No | Server address (uses AZURE_SQL_SERVER if not provided) |

Example:

execute_sql_query query: "SELECT TOP 10 * FROM Users"

list_tables

List all tables in the database with their schemas and row counts.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | database | string | No | Database name | | server | string | No | Server address | | schema | string | No | Filter by schema name (e.g., 'dbo') |

Example:

list_tables schema: "dbo"

get_table_schema

Get the schema (columns, types, constraints) of a specific table.

Parameters: | Name | Type | Required | Description | |------|------|----------|-------------| | table | string | Yes | Table name (can include schema: 'dbo.TableName') | | database | string | No | Database name | | server | string | No | Server address |

Example:

get_table_schema table: "dbo.Users"

Authentication

This server uses DefaultAzureCredential from the Azure Identity SDK, which tries multiple authentication methods in order:

1. Environment variables (AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, AZURE_TENANT_ID)
2. Managed Identity (when running in Azure)
3. Azure CLI (az login)
4. Azure PowerShell
5. Interactive browser (if enabled)

For local development, the easiest method is to use Azure CLI:

az login

Development

# Clone the repository
git clone https://github.com/user/azure-sqlserver-mcp.git
cd azure-sqlserver-mcp

# Install dependencies
npm install

# Build
npm run build

# Run directly
npm start

# Run unit tests
npm test

# Run unit tests with coverage
npm run test:coverage

# Run E2E tests (requires Azure connection)
# PowerShell:
$env:RUN_E2E_TESTS="true"; npm run test:e2e
# Bash/Linux/Mac:
RUN_E2E_TESTS=true npm run test:e2e

Publishing to npm

# 1. Login to npm (first time only)
npm login

# 2. Build the project
npm run build

# 3. Preview what will be published
npm pack --dry-run

# 4. Publish
npm publish

# 5. For subsequent releases, bump version first
npm version patch  # 0.1.0 -> 0.1.1
npm version minor  # 0.1.0 -> 0.2.0
npm version major  # 0.1.0 -> 1.0.0
npm publish

Testing

The project includes comprehensive unit tests with 88% code coverage:

• Unit Tests: Test all handler methods and server functionality with mocked dependencies
• E2E Tests: Available for testing against a real Azure SQL Database (skipped by default)

To run E2E tests, set the RUN_E2E_TESTS=true environment variable and ensure you're logged into Azure CLI.

License

MIT