snowflake_mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code when working with the Snowflake MCP Server repository.

Repository Overview

This is a Model Context Protocol (MCP) server that enables Claude to interact with Snowflake data warehouses. It's a learning project demonstrating how to build custom MCP integrations for data engineering workflows.

Project Structure

snowflake-mcp/
├── server.py              # Main MCP server implementation
├── test_connection.py     # Connection testing utility
├── requirements.txt       # Python dependencies
├── .env.example          # Environment variable template
├── README.md             # User-facing documentation
├── QUICKSTART.md         # 5-minute setup guide
└── CLAUDE.md            # This file (Claude Code instructions)

Key Components

server.py

• SnowflakeMCPServer class: Main server implementation
• 4 MCP Tools:
  • query_snowflake: Execute SQL queries
  • list_tables: List tables in schema
  • describe_table: Get table structure
  • check_table_freshness: Monitor data recency
• Uses snowflake-connector-python for database connectivity
• Implements MCP protocol via mcp SDK

Architecture Patterns

• Connection pooling: Single connection reused across tool calls
• Environment-based config: Credentials from environment variables
• Error handling: Try-catch blocks with user-friendly error messages
• Security: Never commits credentials (.gitignore protects .env)

Working with This Repository

Adding New Tools

When users request new MCP tools, follow this pattern:

1. Add tool function in SnowflakeMCPServer._setup_tools():

@self.app.call_tool()
async def my_new_tool(arguments: dict[str, Any]) -> list[TextContent]:
    """Tool description"""
    param = arguments.get("param_name")

    try:
        conn = self._get_connection()
        cursor = conn.cursor()
        cursor.execute("YOUR SQL")
        results = cursor.fetchall()

        return [TextContent(type="text", text=formatted_output)]
    except Exception as e:
        return [TextContent(type="text", text=f"Error: {str(e)}")]