npm package: @ggball/mcp-database
Description: Multi-database MCP Server - Connect and query SQL Server, MySQL, and OceanBase via MCP
Author: ggball
Latest version: 2.0.1

# MCP SQL Server (Node.js/TypeScript)

A Model Context Protocol (MCP) server for connecting to and querying SQL Server, MySQL, and OceanBase databases, built with TypeScript and Node.js.

## What is MCP?

MCP (Model Context Protocol) is an open protocol that allows AI assistants to securely and standardly interact with external data sources and tools. Through MCP servers, AI assistants can:

- Directly connect to databases to execute queries
- Call external APIs to get real-time data
- Access file systems and cloud storage
- Execute custom business logic

MCP architecture contains two core components:
- **MCP Client**: Built into AI assistants (like Claude Desktop), responsible for communicating with servers
- **MCP Server**: Independent processes that provide specific tools and data access capabilities

## Features

- List all available databases
- List all tables in a specific database
- Get table structure information (columns, data types, primary keys, etc.)
- Execute safe SELECT queries (limited to 1000 rows)
- Get table index information
- Get table statistics (row count, size, etc.)
- Connection pool management for improved performance

## Installation

### Via npm (Global Installation)

```bash
npm install -g @ggball/mcp-database
```

After global installation, the `mcp-database` command will be available system-wide.

### Via npx (Without Installation)

```bash
npx @ggball/mcp-database
```

### From Source

#### 1. System Requirements

- Node.js 18.0.0 or higher
- npm 9.0.0 or higher
- SQL Server (any version)

#### 2. Install Dependencies

```bash
npm install
```

### 3. Build the Project

```bash
npm run build
```

## Configuration

### Environment Variables

Create a `.env` file or set the following environment variables:

#### Unified Configuration (Recommended)

Use `DB_*` prefix for a simplified configuration that works with all database types:

| Environment Variable | Description | Default Value |
|---------------------|-------------|---------------|
| `DB_TYPE` | Database type: `sqlserver`, `mysql`, or `oceanbase` | `sqlserver` |
| `DB_HOST` | Server address | `localhost` |
| `DB_PORT` | Port number (auto-defaults by DB_TYPE) | `1433` / `3306` / `2881` |
| `DB_USER` | Username | `root` |
| `DB_PASSWORD` | Password | (empty) |
| `DB_DATABASE` | Default database | `master` |
| `DB_CHARSET` | Character set (MySQL/OceanBase) | `utf8mb4` |
| `DB_ENCRYPT` | Enable encryption (SQL Server) | `true` |
| `DB_TRUST_SERVER_CERTIFICATE` | Trust server certificate (SQL Server) | `true` |
| `DB_REQUEST_TIMEOUT` | Request timeout in milliseconds | `30000` |

#### Database-Specific Overrides (Optional)

For advanced scenarios, you can override specific settings for each database type:

| Environment Variable | Description | Default Value |
|---------------------|-------------|---------------|
| `SQLSERVER_HOST` | SQL Server host (overrides `DB_HOST`) | - |
| `SQLSERVER_PORT` | SQL Server port (overrides `DB_PORT`) | - |
| `SQLSERVER_USER` | SQL Server user (overrides `DB_USER`) | - |
| `SQLSERVER_PASSWORD` | SQL Server password (overrides `DB_PASSWORD`) | - |
| `SQLSERVER_DATABASE` | SQL Server database (overrides `DB_DATABASE`) | - |
| `SQLSERVER_ENCRYPT` | SQL Server encryption (overrides `DB_ENCRYPT`) | - |
| `SQLSERVER_TRUST_SERVER_CERTIFICATE` | Trust certificate (overrides `DB_TRUST_SERVER_CERTIFICATE`) | - |
| `MYSQL_HOST` | MySQL host (overrides `DB_HOST`) | - |
| `MYSQL_PORT` | MySQL port (overrides `DB_PORT`) | - |
| `MYSQL_USER` | MySQL user (overrides `DB_USER`) | - |
| `MYSQL_PASSWORD` | MySQL password (overrides `DB_PASSWORD`) | - |
| `MYSQL_DATABASE` | MySQL database (overrides `DB_DATABASE`) | - |
| `MYSQL_CHARSET` | MySQL charset (overrides `DB_CHARSET`) | - |
| `OCEANBASE_HOST` | OceanBase host (overrides `DB_HOST`) | - |
| `OCEANBASE_PORT` | OceanBase port (overrides `DB_PORT`) | - |
| `OCEANBASE_USER` | OceanBase user (overrides `DB_USER`) | - |
| `OCEANBASE_PASSWORD` | OceanBase password (overrides `DB_PASSWORD`) | - |
| `OCEANBASE_DATABASE` | OceanBase database (overrides `DB_DATABASE`) | - |
| `OCEANBASE_CHARSET` | OceanBase charset (overrides `DB_CHARSET`) | - |

**Priority:** Specific DB env vars (e.g., `SQLSERVER_HOST`) > Unified `DB_*` vars > Defaults

### Example .env File

#### Simple Configuration (Single Database)

```env
# SQL Server (default)
DB_TYPE=sqlserver
DB_HOST=localhost
DB_PORT=1433
DB_USER=sa
DB_PASSWORD=YourPassword123
DB_DATABASE=MyDatabase
DB_ENCRYPT=true
DB_TRUST_SERVER_CERTIFICATE=true
```

#### MySQL Configuration

```env
DB_TYPE=mysql
DB_HOST=localhost
DB_PORT=3306
DB_USER=root
DB_PASSWORD=YourPassword123
DB_DATABASE=mydb
DB_CHARSET=utf8mb4
```

#### OceanBase Configuration

```env
DB_TYPE=oceanbase
DB_HOST=localhost
DB_PORT=2881
DB_USER=root
DB_PASSWORD=YourPassword123
DB_DATABASE=mydb
DB_CHARSET=utf8mb4
```

## Usage

### Running the Server

```bash
npm start
```

Or for development with auto-rebuild:

```bash
npm run dev
```

### Configuration in Claude Desktop

#### Config File Location

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

#### Option 1: Using Global Installation (Recommended)

If you installed the package globally:

```json
{
  "mcpServers": {
    "sqlserver": {
      "command": "mcp-sqlserver",
      "env": {
        "SQLSERVER_HOST": "localhost",
        "SQLSERVER_PORT": "1433",
        "SQLSERVER_USER": "sa",
        "SQLSERVER_PASSWORD": "YourPassword123",
        "SQLSERVER_DATABASE": "MyDatabase"
      }
    }
  }
}
```

#### Option 2: Using npx

```json
{
  "mcpServers": {
    "sqlserver": {
      "command": "npx",
      "args": ["@ggball/mcp-database"],
      "env": {
        "SQLSERVER_HOST": "localhost",
        "SQLSERVER_PORT": "1433",
        "SQLSERVER_USER": "sa",
        "SQLSERVER_PASSWORD": "YourPassword123",
        "SQLSERVER_DATABASE": "MyDatabase"
      }
    }
  }
}
```

#### Option 3: From Source

```json
{
  "mcpServers": {
    "sqlserver": {
      "command": "node",
      "args": ["/path/to/mcp-sqlserver-npm/dist/index.js"],
      "env": {
        "SQLSERVER_HOST": "localhost",
        "SQLSERVER_PORT": "1433",
        "SQLSERVER_USER": "sa",
        "SQLSERVER_PASSWORD": "YourPassword123",
        "SQLSERVER_DATABASE": "MyDatabase"
      }
    }
  }
}
```

Restart Claude Desktop after configuration.

### Configuration in Claude Code

#### Config File Location

- **macOS/Linux**: `~/.config/claude-code/config.json`
- **Windows**: `%APPDATA%\claude-code\config.json`

#### Option 1: Using Global Installation (Recommended)

```json
{
  "mcpServers": {
    "sqlserver": {
      "command": "mcp-sqlserver",
      "env": {
        "SQLSERVER_HOST": "localhost",
        "SQLSERVER_PORT": "1433",
        "SQLSERVER_USER": "sa",
        "SQLSERVER_PASSWORD": "YourPassword123",
        "SQLSERVER_DATABASE": "MyDatabase"
      }
    }
  }
}
```

#### Option 2: Using npx

```json
{
  "mcpServers": {
    "sqlserver": {
      "command": "npx",
      "args": ["@ggball/mcp-database"],
      "env": {
        "SQLSERVER_HOST": "localhost",
        "SQLSERVER_PORT": "1433",
        "SQLSERVER_USER": "sa",
        "SQLSERVER_PASSWORD": "YourPassword123",
        "SQLSERVER_DATABASE": "MyDatabase"
      }
    }
  }
}
```

#### Option 3: From Source

```json
{
  "mcpServers": {
    "sqlserver": {
      "command": "node",
      "args": ["/path/to/mcp-sqlserver-npm/dist/index.js"],
      "env": {
        "SQLSERVER_HOST": "localhost",
        "SQLSERVER_PORT": "1433",
        "SQLSERVER_USER": "sa",
        "SQLSERVER_PASSWORD": "YourPassword123",
        "SQLSERVER_DATABASE": "MyDatabase"
      }
    }
  }
}
```

Restart Claude Code after configuration.

## Available Tools

### 1. list_databases

Lists all SQL Server databases (excluding system databases).

```
Tool name: list_databases
Parameters: None
```

**Example:**
```
List all available databases
```

### 2. list_tables

Lists all tables in a specific database.

```
Tool name: list_tables
Parameters:
  - database (required): Database name
  - schema (optional): Schema name, defaults to "dbo"
```

**Example:**
```
List all tables in MyDatabase
```

### 3. describe_table

Gets table structure information including columns, data types, nullable, primary keys, etc.

```
Tool name: describe_table
Parameters:
  - database (required): Database name
  - table (required): Table name
  - schema (optional): Schema name, defaults to "dbo"
```

**Example:**
```
Show the structure of the Users table in MyDatabase
```

### 4. execute_query

Executes SQL SELECT queries (only SELECT and WITH allowed, limited to 1000 rows).

```
Tool name: execute_query
Parameters:
  - query (required): SQL query statement
  - database (optional): Database name, defaults to configured database
```

**Example:**
```
Query users older than 18 from the Users table
```

### 5. get_table_indexes

Gets index information for a table.

```
Tool name: get_table_indexes
Parameters:
  - database (required): Database name
  - table (required): Table name
  - schema (optional): Schema name, defaults to "dbo"
```

**Example:**
```
Get index information for the Users table
```

### 6. get_table_stats

Gets table statistics including row count and storage size.

```
Tool name: get_table_stats
Parameters:
  - database (required): Database name
  - table (required): Table name
  - schema (optional): Schema name, defaults to "dbo"
```

**Example:**
```
Get statistics for the Users table
```

## Usage Examples

### Scenario 1: Explore Database

```
You: List all available databases
Claude: [calls list_databases] ...

You: Show what tables are in MyDatabase
Claude: [calls list_tables] ...
```

### Scenario 2: Query Data

```
You: Query the last 10 orders from Orders table
Claude: [calls describe_table to understand table structure]
      [calls execute_query to perform query] ...
```

### Scenario 3: Analyze Table Structure

```
You: Analyze the structure and indexes of Users table
Claude: [calls describe_table]
      [calls get_table_indexes]
      [calls get_table_stats] ...
```

## Security Notes

- `execute_query` tool only allows SELECT and WITH queries
- Automatically blocks statements containing dangerous keywords (DROP, DELETE, UPDATE, etc.)
- Query results are limited to 1000 rows

## Development

### Project Structure

```
mcp-database/
├── src/
│   ├── index.ts       # Main server entry point
│   ├── config.ts      # Configuration management
│   └── connection.ts  # Connection pool implementation
├── dist/              # Compiled output
├── package.json
├── tsconfig.json
└── README.md
```

### Scripts

- `npm run build` - Compile TypeScript
- `npm run dev` - Compile and run in development mode
- `npm start` - Run the compiled server
- `npm run watch` - Watch mode for TypeScript compilation

### Dependencies

- `@modelcontextprotocol/sdk` - Official MCP SDK for TypeScript
- `tedious` - SQL Server connector for Node.js
- `zod` - Schema validation
- `dotenv` - Environment variable management

## License

MIT License

## Sources

- [MCP TypeScript SDK GitHub](https://github.com/modelcontextprotocol/typescript-sdk)
- [NPM Package: @modelcontextprotocol/sdk](https://www.npmjs.com/package/@modelcontextprotocol/sdk)
- [GitHub Repository](https://github.com/a1667834841/mcp-sqlserver)
- [掘金 - MCP TypeScript SDK 核心概念](https://juejin.cn/post/7517532575008866367)
- [Mojotv.cn - MCP TypeScript SDK 教程](https://zh.mojotv.cn/misc/mcp-node)