npm package: @naganpm/snowflake-mcp-server
Description: MCP server for Snowflake database integration
Latest version: 1.0.9

# Snowflake MCP Server

A **Model Context Protocol (MCP) server** for Snowflake database integration, built with TypeScript and compliant with Snowflake's MCP standards (revision 2025-06-18).

## Features

- 🚀 **MCP Protocol Compliant** - Follows Snowflake's MCP standards
- 🔧 **System SQL Execution** - Execute SQL queries with proper context management
- 📊 **Metadata Queries** - Query databases, schemas, tables, columns, and warehouses
- 🏭 **Warehouse Management** - Start, stop, suspend, and resume warehouses
- 📍 **Session Information** - Get current session and connection status
- 🛡️ **Error Handling** - Comprehensive error handling and logging
- 💻 **TypeScript Support** - Full TypeScript implementation
- 🔌 **Dual Mode** - MCP server (primary) + Express API (optional)

## Installation

```bash
npm install @naganpm/snowflake-mcp-server
```

Or for development:
```bash
npm install
```

## Configuration

### MCP Configuration (Primary Method)

#### Using continue.dev or Claude Desktop

```json
{
  "mcpServers": {
    "snowflake": {
      "command": "npx",
      "args": ["-y", "@naganpm/snowflake-mcp-server@latest"],
      "env": {
        "SNOWFLAKE_ACCOUNT": "your-account.us-east-2.aws",
        "SNOWFLAKE_USERNAME": "your-username",
        "SNOWFLAKE_PASSWORD": "your-password",
        "SNOWFLAKE_WAREHOUSE": "your-warehouse",
        "SNOWFLAKE_DATABASE": "your-database",
        "SNOWFLAKE_SCHEMA": "your-schema"
      }
    }
  }
}
```

### Environment Configuration

1. Copy `.env.example` to `.env`:
```bash
cp .env.example .env
```

2. Update `.env` with your Snowflake credentials:
```env
SNOWFLAKE_ACCOUNT=your-account.region.cloud
SNOWFLAKE_USERNAME=your-username
SNOWFLAKE_PASSWORD=your-password
SNOWFLAKE_WAREHOUSE=YOUR_WAREHOUSE
SNOWFLAKE_DATABASE=YOUR_DATABASE
SNOWFLAKE_SCHEMA=YOUR_SCHEMA
```

## Usage

### MCP Server (Primary)

```bash
# Development
npm run dev

# Production
npm run build && npm start
```

### Express API Server (Optional)

```bash
# Development
npm run dev:express

# Production
npm run build && npm run start:express
```

## MCP Tools

### 1. `system_execute_sql`
Execute SQL queries with optional context switching.

**Parameters:**
- `sql` (required): SQL query to execute
- `parameters` (optional): Bind parameters
- `warehouse` (optional): Warehouse context
- `database` (optional): Database context
- `schema` (optional): Schema context

**Example:**
```json
{
  "name": "system_execute_sql",
  "arguments": {
    "sql": "SELECT COUNT(*) FROM my_table",
    "warehouse": "COMPUTE_WH"
  }
}
```

### 2. `snowflake_metadata_query`
Query Snowflake metadata information.

**Parameters:**
- `metadata_type` (required): One of: `databases`, `schemas`, `tables`, `columns`, `warehouses`, `users`, `roles`
- `database_name` (optional): Required for schemas/tables/columns
- `schema_name` (optional): Required for tables/columns
- `table_name` (optional): Required for columns

**Example:**
```json
{
  "name": "snowflake_metadata_query",
  "arguments": {
    "metadata_type": "tables",
    "database_name": "MY_DB",
    "schema_name": "PUBLIC"
  }
}
```

### 3. `snowflake_session_info`
Get current session information and connection status.

**Example:**
```json
{
  "name": "snowflake_session_info",
  "arguments": {}
}
```

### 4. `snowflake_warehouse_management`
Manage Snowflake warehouses.

**Parameters:**
- `action` (required): One of: `list`, `start`, `stop`, `suspend`, `resume`, `describe`
- `warehouse_name` (optional): Required for start/stop/suspend/resume/describe

**Example:**
```json
{
  "name": "snowflake_warehouse_management",
  "arguments": {
    "action": "resume",
    "warehouse_name": "COMPUTE_WH"
  }
}
```

## API Endpoints (Express Mode)

If using the Express server (`npm run dev:express`), the following REST endpoints are available:

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/health` | Health check |
| POST | `/api/snowflake/query` | Execute SQL query |
| GET | `/api/snowflake/databases` | List databases |
| GET | `/api/snowflake/schemas` | List schemas |
| GET | `/api/snowflake/tables` | List tables |
| GET | `/api/snowflake/tables/:name/describe` | Describe table |
| GET | `/api/snowflake/warehouses` | List warehouses |
| GET | `/api/snowflake/session` | Get session info |
| GET | `/api/snowflake/status` | Connection status |

## Response Format

### MCP Responses
```json
{
  "success": true,
  "data": {
    "columns": ["column1", "column2"],
    "rows": [["value1", "value2"]],
    "rowCount": 1,
    "executionTime": 142,
    "query": "SELECT column1, column2 FROM table"
  },
  "timestamp": "2026-02-17T10:30:00.000Z"
}
```

### Error Responses
```json
{
  "success": false,
  "error": "SQL Error: Object 'INVALID_TABLE' does not exist (Code: 002003)",
  "tool": "system_execute_sql",
  "timestamp": "2026-02-17T10:30:00.000Z"
}
```

## Development

### Project Structure
```
.
├── src/
│   ├── mcp-server.ts              # MCP server (primary entry point)
│   ├── index.ts                   # Express server (optional)
│   ├── services/
│   │   └── snowflake.service.ts   # Snowflake service
│   └── routes/
│       └── snowflake.routes.ts    # Express API routes
├── package.json
├── tsconfig.json
└── .env
```

### Scripts

- `npm run dev` - Run MCP server in development mode
- `npm run dev:express` - Run Express server in development mode
- `npm run build` - Build TypeScript to JavaScript
- `npm run start` - Run production MCP server
- `npm run start:express` - Run production Express server
- `npm run watch` - Watch mode for development
- `npm run clean` - Clean dist folder

## Snowflake MCP Standards Compliance

This server follows Snowflake's MCP documentation standards:

- ✅ MCP Protocol revision "2025-06-18"
- ✅ Standardized tool naming conventions
- ✅ Proper error handling and logging
- ✅ Context-aware SQL execution
- ✅ Metadata query capabilities
- ✅ Session management
- ✅ Warehouse lifecycle management

## References

- [Snowflake Cortex Agents MCP Documentation](https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-mcp)

## Security Notes

- Use environment variables for credentials
- Avoid hardcoded passwords or tokens
- Follow least-privilege access principles
- Consider OAuth authentication for production use

## License

MIT