simple_snowflake_mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project

A single-process MCP (Model Context Protocol) server that exposes Snowflake to MCP clients (Claude Desktop, VS Code) over stdio. Designed to run behind a corporate proxy. Python ≥3.10, packaged with uv/hatchling, published to PyPI as simple-snowflake-mcp.

Commands

uv sync --all-extras        # Install all deps incl. dev (creates venv)
uv run simple-snowflake-mcp # Run the server (stdio)
uv run pytest               # Run tests
uv run pytest tests/test_snowflake.py::test_list_snowflake_warehouses  # Single test
uv run ruff check .         # Lint
uv run ruff format .        # Format
uv run mypy src             # Type check
uv build                    # Build distribution

Tests are async (asyncio_mode = "auto") and mock snowflake.connector.connect — they run in CI with no credentials and never touch a live account. tests/test_security.py holds the security regression tests (one per audit finding); tests/test_snowflake.py holds tool-dispatch smoke tests.

CI: .github/workflows/ci.yml runs ruff + pytest on push/PR; .github/workflows/workflow.yml builds and publishes to PyPI on v* tags.

Architecture

Essentially everything lives in src/simple_snowflake_mcp/server.py (~900 lines). __init__.py just calls asyncio.run(server.main()).

The server is built on the mcp library's Server object (module-global server). MCP capabilities are registered via decorators, all defined in server.py:

• @server.list_tools() / @server.call_tool() — the tools
• @server.list_resources() / @server.read_resource() / @server.subscribe_resource() / @server.unsubscribe_resource() — Snowflake resources + subscription notifications
• @server.list_prompts() / @server.get_prompt() — prompts

handle_call_tool is a single large if/elif dispatch on tool name. All Snowflake access funnels through one chokepoint, _safe_snowflake_execute(query, description, *, is_user_sql=False, row_limit=None) — this is deliberate and security-critical. It applies the read-only guard, executes via a reused connection (_get_connection/_reset_connection) under a threading.Lock, bounds rows via fetchmany, and returns {"success", "data", "error"} with client-safe (generic) error text while logging full detail. The two user SQL tools both route through _run_user_query, which calls the chokepoint with is_user_sql=True. Internal server queries (resources/prompts) call it with the default is_user_sql=False.