{"_id":"snowflake-mcp-server","_rev":"8-587f76e524778859dd1e0688d5d3de6b","name":"snowflake-mcp-server","dist-tags":{"latest":"1.0.4"},"versions":{"1.0.3":{"name":"snowflake-mcp-server","version":"1.0.3","keywords":["mcp","model-context-protocol","snowflake","database","llm","ai"],"author":{"url":"MikdanTech.com","name":"Mikdanjey","email":"mikdanjey@gmail.com"},"license":"MIT","_id":"snowflake-mcp-server@1.0.3","maintainers":[{"name":"mikdanjey","email":"mikdanjey@gmail.com"}],"homepage":"https://github.com/mikdanjey/snowflake-mcp-server#readme","bugs":{"url":"https://github.com/mikdanjey/snowflake-mcp-server/issues"},"bin":{"snowflake-mcp-server":"dist/main.js"},"dist":{"shasum":"3b4002b3940641f2f65f42628a5b0bfec4cb74da","tarball":"https://registry.npmjs.org/snowflake-mcp-server/-/snowflake-mcp-server-1.0.3.tgz","fileCount":148,"integrity":"sha512-Rh8nTXctjWHdydlv6angHGGF/oqbpg2I4mL/Ku5HuWMTGM1uIkwp59hTS3K9+FSvoGHYPIsrQxbzfWK7wKCwnA==","signatures":[{"sig":"MEUCIAIG65eBt+rVEcv4RnE5V4H/VPCGtt91E+qS6B7TDmocAiEAnZUyE5rEvXVHnmBlE3+W1AYL0TuJQ4++o2b7q3bN/w8=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":577562},"main":"dist/main.js","type":"module","types":"./dist/main.d.ts","engines":{"node":">=20.0.0"},"gitHead":"36311d66ff1d4435563450be83533732f6eaac51","scripts":{"dev":"tsx src/main.ts","lint":"eslint src/**/*.ts tests/**/*.ts","test":"jest","build":"tsc","clean":"rimraf dist coverage eslint-report.json","clear":"rm -rf dist node_modules coverage .scannerwork package-lock.json yarn.lock next-env.d.ts yarn-error.log eslint-report.json output.log snowflake.log error.log","start":"node dist/main.js","deploy":"bash scripts/deploy.sh","format":"prettier --log-level log --write .","lint:ci":"eslint src/**/*.ts tests/**/*.ts --format=json --output-file=eslint-report.json","prepack":"npm run build:prod","test:ci":"jest --coverage --ci --watchAll=false --passWithNoTests","lint:fix":"eslint src/**/*.ts tests/**/*.ts --fix","prebuild":"npm run clean","validate":"npm run typecheck && npm run lint && npm run format:check && npm run test:ci","dev:watch":"tsx watch src/main.ts","test:unit":"jest --testPathPattern=unit","typecheck":"tsc --noEmit","build:prod":"npm run clean && npm run lint && npm run test && tsc --sourceMap false","docker:run":"docker run --rm -it snowflake-mcp-server","test:watch":"jest --watch","build:watch":"tsc --watch","build:script":"bash scripts/build.sh","docker:build":"docker build -t snowflake-mcp-server .","format:check":"prettier --check \"src/**/*.ts\" \"tests/**/*.ts\" \"*.{js,json,md}\"","test:coverage":"jest --coverage","test:integration":"jest --testPathPattern=integration","test:performance":"jest --testPathPattern=performance --verbose --runInBand","build:script:prod":"bash scripts/build.sh production","docker:compose:up":"docker-compose up -d","docker:compose:dev":"docker-compose --profile dev up -d","docker:compose:down":"docker-compose down"},"_npmUser":{"name":"mikdanjey","email":"mikdanjey@gmail.com"},"repository":{"url":"git+https://github.com/mikdanjey/snowflake-mcp-server.git","type":"git"},"_npmVersion":"11.4.2","description":"Model Context Protocol server for Snowflake database integration","directories":{},"_nodeVersion":"22.18.0","dependencies":{"zod":"3.22.4","dotenv":"16.6.1","snowflake-sdk":"^2.1.3","@modelcontextprotocol/sdk":"^1.17.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.3","jest":"^29.7.0","eslint":"^9.32.0","rimraf":"^5.0.5","ts-jest":"^29.4.1","prettier":"^3.6.2","@eslint/js":"^9.32.0","typescript":"^5.9.2","@types/jest":"^29.5.8","@types/node":"^20.9.0","typescript-eslint":"^8.39.0","eslint-config-prettier":"^9.0.0","eslint-plugin-prettier":"^5.5.4","@typescript-eslint/parser":"^8.39.0","@typescript-eslint/eslint-plugin":"^8.39.0"},"_npmOperationalInternal":{"tmp":"tmp/snowflake-mcp-server_1.0.3_1754657547640_0.34945038240684556","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"snowflake-mcp-server","version":"1.0.4","description":"Model Context Protocol server for Snowflake database integration","main":"dist/main.js","type":"module","author":{"name":"Mikdanjey","email":"mikdanjey@gmail.com","url":"MikdanTech.com"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/mikdanjey/snowflake-mcp-server.git"},"bin":{"snowflake-mcp-server":"dist/main.js"},"keywords":["mcp","model-context-protocol","snowflake","database","llm","ai"],"scripts":{"build":"tsc","build:prod":"npm run clean && npm run lint && npm run test && tsc --sourceMap false","build:watch":"tsc --watch","dev":"tsx src/main.ts","dev:watch":"tsx watch src/main.ts","start":"node dist/main.js","test":"jest","test:watch":"jest --watch","test:coverage":"jest --coverage","test:unit":"jest --testPathPattern=unit","test:integration":"jest --testPathPattern=integration","test:performance":"jest --testPathPattern=performance --verbose --runInBand","test:ci":"jest --coverage --ci --watchAll=false --passWithNoTests","lint":"eslint src/**/*.ts tests/**/*.ts","lint:fix":"eslint src/**/*.ts tests/**/*.ts --fix","lint:ci":"eslint src/**/*.ts tests/**/*.ts --format=json --output-file=eslint-report.json","format":"prettier --log-level log --write .","format:check":"prettier --check \"src/**/*.ts\" \"tests/**/*.ts\" \"*.{js,json,md}\"","typecheck":"tsc --noEmit","clean":"rimraf dist coverage eslint-report.json","prebuild":"npm run clean","prepack":"npm run build:prod","validate":"npm run typecheck && npm run lint && npm run format:check && npm run test:ci","docker:build":"docker build -t snowflake-mcp-server .","docker:run":"docker run --rm -it snowflake-mcp-server","docker:compose:up":"docker-compose up -d","docker:compose:down":"docker-compose down","docker:compose:dev":"docker-compose --profile dev up -d","build:script":"bash scripts/build.sh","build:script:prod":"bash scripts/build.sh production","deploy":"bash scripts/deploy.sh","clear":"rm -rf dist node_modules coverage .scannerwork package-lock.json yarn.lock next-env.d.ts yarn-error.log eslint-report.json output.log snowflake.log error.log"},"dependencies":{"@modelcontextprotocol/sdk":"^1.17.1","dotenv":"16.6.1","snowflake-sdk":"^2.1.3","zod":"3.22.4"},"devDependencies":{"@eslint/js":"^9.32.0","@types/jest":"^29.5.8","@types/node":"^20.9.0","@typescript-eslint/eslint-plugin":"^8.39.0","@typescript-eslint/parser":"^8.39.0","eslint":"^9.32.0","eslint-config-prettier":"^9.0.0","eslint-plugin-prettier":"^5.5.4","jest":"^29.7.0","prettier":"^3.6.2","rimraf":"^5.0.5","ts-jest":"^29.4.1","tsx":"^4.20.3","typescript":"^5.9.2","typescript-eslint":"^8.39.0"},"engines":{"node":">=20.0.0"},"_id":"snowflake-mcp-server@1.0.4","gitHead":"670236a04137b2f32e91e1f02cb97b6f4ec2aa5a","types":"./dist/main.d.ts","bugs":{"url":"https://github.com/mikdanjey/snowflake-mcp-server/issues"},"homepage":"https://github.com/mikdanjey/snowflake-mcp-server#readme","_nodeVersion":"22.18.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-YaDh6mpbfmFLbzt0PtYFAwQl/gpqwJGjcsTbEWKBTcTsDXEh9ZhLwU3/EqZKJEVHbmnofgODqs4XbQzdj2XJTQ==","shasum":"7c77d352c47b842b494562e9a60b312d4b3a6432","tarball":"https://registry.npmjs.org/snowflake-mcp-server/-/snowflake-mcp-server-1.0.4.tgz","fileCount":148,"unpackedSize":577845,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCJUDKv7Aaiu5ye1cnhgW0Q7IJxn52GOm4zDJX+tMK1AgIgRrgDU3I0z9rV9MYsAEsw7vqVpj6Wsn/C4ILaJUiEq40="}]},"_npmUser":{"name":"mikdanjey","email":"mikdanjey@gmail.com"},"directories":{},"maintainers":[{"name":"mikdanjey","email":"mikdanjey@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/snowflake-mcp-server_1.0.4_1754659067667_0.9002682076480804"},"_hasShrinkwrap":false}},"time":{"created":"2025-08-06T19:02:03.335Z","modified":"2025-08-08T13:17:48.066Z","1.0.0":"2025-08-06T19:02:03.516Z","1.0.1":"2025-08-06T19:45:11.387Z","1.0.2":"2025-08-06T20:56:20.236Z","1.0.3":"2025-08-08T12:52:27.829Z","1.0.4":"2025-08-08T13:17:47.868Z"},"bugs":{"url":"https://github.com/mikdanjey/snowflake-mcp-server/issues"},"author":{"name":"Mikdanjey","email":"mikdanjey@gmail.com","url":"MikdanTech.com"},"license":"MIT","homepage":"https://github.com/mikdanjey/snowflake-mcp-server#readme","keywords":["mcp","model-context-protocol","snowflake","database","llm","ai"],"repository":{"type":"git","url":"git+https://github.com/mikdanjey/snowflake-mcp-server.git"},"description":"Model Context Protocol server for Snowflake database integration","maintainers":[{"name":"mikdanjey","email":"mikdanjey@gmail.com"}],"readme":"# Snowflake MCP Server\n\nA Model Context Protocol (MCP) server that enables LLM agents to securely connect to and query Snowflake databases. This server acts as a bridge between natural language processing agents and Snowflake's data warehouse, allowing for seamless SQL execution through structured input/output over STDIO.\n\n## Features\n\n- **MCP Protocol Compliance**: Full compatibility with the Model Context Protocol specification\n- **Secure Authentication**: Support for both password and external browser (SSO) authentication\n- **SQL Validation**: Comprehensive input validation and sanitization using Zod schemas\n- **Error Handling**: Robust error handling with detailed diagnostic information\n- **Performance Optimized**: Async query execution with connection pooling and timeout management\n- **Comprehensive Logging**: Structured logging with configurable levels\n- **TypeScript**: Full TypeScript support with comprehensive type definitions\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 20.0.0 or higher\n- Access to a Snowflake account\n- Valid Snowflake credentials\n\n## Usage\n\n### Basic MCP Integration\n\nThe server exposes a `snowflake.query` resource that accepts SQL queries and returns structured results. Here's how to integrate it with an MCP client:\n\n```json\n{\n  \"mcpServers\": {\n    \"snowflake-mcp-server\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"snowflake-mcp-server\"],\n      \"env\": {\n        \"SNOWFLAKE_ACCOUNT\": \"NLTFXXX-KB70000\",\n        \"SNOWFLAKE_USER\": \"MIKDANJEY\",\n        \"SNOWFLAKE_DATABASE\": \"DEMO\",\n        \"SNOWFLAKE_SCHEMA\": \"PUBLIC\",\n        \"SNOWFLAKE_WAREHOUSE\": \"COMPUTE_WH\",\n        \"SNOWFLAKE_ROLE\": \"SYSADMIN\",\n        \"SNOWFLAKE_AUTHENTICATOR\": \"snowflake\",\n        \"SNOWFLAKE_PASSWORD\": \"HZtJXuz6Efq2MNC\",\n        \"LOG_LEVEL\": \"info\"\n      }\n    }\n  }\n}\n```\n\n### Installation\n\n1. **Clone and install dependencies:**\n\n```bash\ngit clone https://github.com/mikdanjey/snowflake-mcp-server.git\ncd snowflake-mcp-server\nnpm install\n```\n\n2. **Configure environment variables:**\n\n```bash\ncp .env.example .env\n```\n\nEdit `.env` with your Snowflake credentials (see [Environment Variables](#environment-variables) section for details).\n\n3. **Build the project:**\n\n```bash\nnpm run build\n```\n\n4. **Run the server:**\n\n```bash\nnpm start\n```\n\nThe server will start and listen for MCP protocol messages over STDIO.\n\n### Command Line Usage\n\nYou can also run the server directly from the command line:\n\n```bash\n# Run in development mode with hot reload\nnpm run dev\n\n# Run with custom log level\nLOG_LEVEL=debug npm start\n\n# Run tests\nnpm test\n\n# Run with coverage\nnpm run test:coverage\n```\n\n### Docker Usage\n\nBuild and run using Docker:\n\n```bash\n# Build Docker image\nnpm run docker:build\n\n# Run container\nnpm run docker:run\n\n# Or use docker-compose\nnpm run docker:compose:up\n```\n\n## Environment Variables\n\nThe server requires several environment variables for Snowflake connection. Copy `.env.example` to `.env` and configure:\n\n### Required Variables\n\n| Variable              | Description                       | Example           |\n| --------------------- | --------------------------------- | ----------------- |\n| `SNOWFLAKE_ACCOUNT`   | Your Snowflake account identifier | `NLTFXXX-KB70000` |\n| `SNOWFLAKE_USER`      | Snowflake username                | `MIKDANJEY`       |\n| `SNOWFLAKE_DATABASE`  | Target database name              | `DEMO`            |\n| `SNOWFLAKE_SCHEMA`    | Target schema name                | `PUBLIC`          |\n| `SNOWFLAKE_WAREHOUSE` | Compute warehouse to use          | `COMPUTE_WH`      |\n| `SNOWFLAKE_ROLE`      | Role to assume                    | `SYSADMIN`        |\n\n### Authentication Variables\n\nChoose one authentication method:\n\n**Password Authentication (default):**\n\n```bash\nSNOWFLAKE_AUTHENTICATOR=snowflake\nSNOWFLAKE_PASSWORD=your_password_here\n```\n\n**External Browser Authentication (SSO):**\n\n```bash\nSNOWFLAKE_AUTHENTICATOR=externalbrowser\n# SNOWFLAKE_PASSWORD not required for SSO\n```\n\n### Optional Variables\n\n| Variable    | Description       | Default | Options                          |\n| ----------- | ----------------- | ------- | -------------------------------- |\n| `LOG_LEVEL` | Logging verbosity | `info`  | `debug`, `info`, `warn`, `error` |\n\n## API Documentation\n\n### Resource: `snowflake.query`\n\nExecute SQL queries against your Snowflake database.\n\n#### Request Format\n\n```typescript\ninterface QueryRequest {\n  sql: string; // The SQL query to execute\n}\n```\n\n#### Response Format\n\n**Success Response:**\n\n```typescript\ninterface QueryResponse {\n  rows: Record<string, any>[]; // Query result rows\n  rowCount: number; // Number of rows returned\n  executionTime: number; // Query execution time in milliseconds\n  metadata?: {\n    columns: ColumnMetadata[]; // Column information\n  };\n}\n\ninterface ColumnMetadata {\n  name: string; // Column name\n  type: string; // Snowflake data type\n  nullable: boolean; // Whether column allows NULL values\n}\n```\n\n**Error Response:**\n\n```typescript\ninterface ErrorResponse {\n  error: {\n    code: string; // Error category code\n    message: string; // Human-readable error message\n    details?: Record<string, any>; // Additional error context\n  };\n}\n```\n\n#### Error Codes\n\n| Code               | Description                                |\n| ------------------ | ------------------------------------------ |\n| `VALIDATION_ERROR` | Invalid SQL input or schema violation      |\n| `CONNECTION_ERROR` | Snowflake authentication or network issues |\n| `EXECUTION_ERROR`  | SQL syntax errors or runtime failures      |\n| `CONFIG_ERROR`     | Missing or invalid environment variables   |\n| `INTERNAL_ERROR`   | Unexpected server errors                   |\n\n## Example Queries\n\n### Basic SELECT Query\n\n```sql\nSELECT * FROM DEMO.PUBLIC.CUSTOMERS LIMIT 10;\n```\n\n**Expected Response:**\n\n```json\n{\n  \"rows\": [\n    {\n      \"CUSTOMER_ID\": 1,\n      \"CUSTOMER_NAME\": \"John Doe\",\n      \"EMAIL\": \"john@example.com\"\n    }\n  ],\n  \"rowCount\": 10,\n  \"executionTime\": 245,\n  \"metadata\": {\n    \"columns\": [\n      {\n        \"name\": \"CUSTOMER_ID\",\n        \"type\": \"NUMBER\",\n        \"nullable\": false\n      },\n      {\n        \"name\": \"CUSTOMER_NAME\",\n        \"type\": \"VARCHAR\",\n        \"nullable\": true\n      }\n    ]\n  }\n}\n```\n\n### Database Information Queries\n\n```sql\n-- Show available databases\nSHOW DATABASES;\n\n-- Describe table structure\nDESCRIBE TABLE DEMO.PUBLIC.CUSTOMERS;\n\n-- Show table information\nSHOW TABLES IN SCHEMA DEMO.PUBLIC;\n```\n\n### Complex Analytical Queries\n\n```sql\n-- Aggregation with grouping\nSELECT\n  REGION,\n  COUNT(*) as CUSTOMER_COUNT,\n  AVG(ORDER_AMOUNT) as AVG_ORDER_AMOUNT\nFROM DEMO.PUBLIC.CUSTOMERS c\nJOIN DEMO.PUBLIC.ORDERS o ON c.CUSTOMER_ID = o.CUSTOMER_ID\nWHERE ORDER_DATE >= '2024-01-01'\nGROUP BY REGION\nORDER BY CUSTOMER_COUNT DESC;\n```\n\n## Development\n\n### Available Scripts\n\n| Script                     | Description                             |\n| -------------------------- | --------------------------------------- |\n| `npm run dev`              | Run in development mode with hot reload |\n| `npm run build`            | Build for production                    |\n| `npm run build:watch`      | Build in watch mode                     |\n| `npm start`                | Start the built server                  |\n| `npm test`                 | Run all tests                           |\n| `npm run test:watch`       | Run tests in watch mode                 |\n| `npm run test:coverage`    | Run tests with coverage report          |\n| `npm run test:unit`        | Run only unit tests                     |\n| `npm run test:integration` | Run only integration tests              |\n| `npm run lint`             | Run ESLint                              |\n| `npm run lint:fix`         | Fix ESLint issues automatically         |\n| `npm run format`           | Format code with Prettier               |\n| `npm run typecheck`        | Run TypeScript type checking            |\n| `npm run validate`         | Run all validation checks               |\n\n### Project Structure\n\n```\nsrc/\n├── clients/           # Snowflake client implementation\n├── handlers/          # MCP resource handlers\n├── server/           # MCP server core\n├── types/            # TypeScript type definitions\n├── utils/            # Utility functions and helpers\n├── validators/       # Input validation logic\n├── application.ts    # Main application class\n├── index.ts         # Public API exports\n└── main.ts          # CLI entry point\ntests/\n├── unit/            # Unit tests\n├── integration/     # Integration tests\n├── performance/     # Performance tests\n└── fixtures/        # Test data and mocks\n```\n\n### Testing\n\nThe project includes comprehensive test coverage:\n\n```bash\n# Run all tests\nnpm test\n\n# Run with coverage\nnpm run test:coverage\n\n# Run specific test types\nnpm run test:unit\nnpm run test:integration\nnpm run test:performance\n\n# Run tests in watch mode\nnpm run test:watch\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### Connection Issues\n\n**Problem:** `CONNECTION_ERROR: Failed to connect to Snowflake`\n\n**Solutions:**\n\n1. Verify your Snowflake account identifier is correct\n2. Check that your username and password are valid\n3. Ensure your IP address is whitelisted in Snowflake\n4. For SSO users, make sure `SNOWFLAKE_AUTHENTICATOR=externalbrowser`\n\n**Problem:** `CONFIG_ERROR: Missing required environment variable`\n\n**Solutions:**\n\n1. Ensure all required environment variables are set in `.env`\n2. Check that `.env` file is in the project root directory\n3. Verify environment variable names match exactly (case-sensitive)\n\n#### Query Execution Issues\n\n**Problem:** `EXECUTION_ERROR: SQL compilation error`\n\n**Solutions:**\n\n1. Verify your SQL syntax is correct\n2. Check that referenced tables and columns exist\n3. Ensure you have proper permissions for the query\n4. Verify the database, schema, and warehouse are accessible\n\n**Problem:** `VALIDATION_ERROR: Invalid SQL input`\n\n**Solutions:**\n\n1. Ensure the SQL query is not empty\n2. Check for unsupported SQL operations\n3. Verify the query structure matches expected format\n\n#### Performance Issues\n\n**Problem:** Queries timing out or running slowly\n\n**Solutions:**\n\n1. Check your warehouse size and scaling policy\n2. Optimize your SQL queries (add indexes, limit results)\n3. Consider breaking complex queries into smaller parts\n4. Monitor Snowflake query history for performance insights\n\n#### Authentication Issues\n\n**Problem:** External browser authentication not working\n\n**Solutions:**\n\n1. Ensure `SNOWFLAKE_AUTHENTICATOR=externalbrowser`\n2. Don't set `SNOWFLAKE_PASSWORD` when using SSO\n3. Check that your organization allows external browser authentication\n4. Verify your browser can access Snowflake login pages\n\n### Debug Mode\n\nEnable debug logging for detailed troubleshooting:\n\n```bash\nLOG_LEVEL=debug npm start\n```\n\nThis will provide detailed logs including:\n\n- Connection attempts and status\n- Query validation steps\n- Execution timing and performance metrics\n- Error stack traces and context\n\n### Getting Help\n\n1. **Check the logs**: Enable debug logging to see detailed error information\n2. **Verify configuration**: Double-check all environment variables\n3. **Test connection**: Use Snowflake's web interface to verify credentials\n4. **Review permissions**: Ensure your user has necessary database permissions\n5. **Check network**: Verify network connectivity to Snowflake\n\n### Performance Monitoring\n\nMonitor server performance using the built-in metrics:\n\n```bash\n# Enable performance logging\nLOG_LEVEL=debug npm start\n\n# Run performance tests\nnpm run test:performance\n```\n\nKey metrics to monitor:\n\n- Query execution time\n- Connection establishment time\n- Memory usage\n- Concurrent request handling\n\n## Security Considerations\n\n- **Environment Variables**: Never commit `.env` files to version control\n- **Credentials**: Use strong passwords and rotate them regularly\n- **Network**: Restrict network access to Snowflake using IP whitelisting\n- **Permissions**: Follow principle of least privilege for database roles\n- **Logging**: Sensitive data is automatically filtered from logs\n\n## Documentation\n\n### Core Documentation\n\n- **[API Documentation](docs/API.md)** - Complete API reference with interfaces and examples\n- **[Configuration Guide](docs/CONFIGURATION.md)** - Comprehensive configuration and environment setup\n- **[Troubleshooting Guide](docs/TROUBLESHOOTING.md)** - Common issues and solutions\n- **[Query Examples](docs/EXAMPLES.md)** - SQL query examples with expected responses\n\n### Quick Links\n\n- [Environment Variables](#environment-variables) - Configuration reference\n- [Example Queries](#example-queries) - Basic usage examples\n- [Troubleshooting](#troubleshooting) - Common issues and solutions\n- [Development](#development) - Development workflow and testing\n\n## License\n\nMIT License - see LICENSE file for details.\n","readmeFilename":"README.md"}