StreamWright MCP Server

The StreamWright Model Context Protocol (MCP) server allows AI assistants and coding agents to understand, scaffold, inspect, and validate StreamWright declarative data pipelines in real time.

By connecting an MCP-compatible client (such as Google Antigravity, GitHub Copilot, Anthropic Claude Desktop, Cursor, Zed, or Windsurf), the AI gains direct access to your local connector catalog, dynamic in-code contracts, and validation compilers — eliminating hallucinations and outdated syntax.

---

Installation

Install the package directly into your active Python environment:

pip install streamwright-mcp

Or using uv:

uv pip install streamwright-mcp

If developing from a local clone:

cd /path/to/streamwright-mcp
pip install -e .

Verify that the CLI command is available:

streamwright-mcp --help
# or via the CLI shorthand
sw mcp --help

---

MCP Tools Reference

The server exposes 6 core tools designed for AI agents:

Tool	Parameters	Description
list_connectors	none	Lists all installed StreamWright connectors discovered via entry points (restapi, postgres, google_ads, etc.) with their version numbers and availability.
get_connector_contract	connector_name: str	Fetches the complete, live in-code contract specification for the connector: source.yaml schema, stream definitions, authentication schemes, DuckDB SQL shaping patterns, and execution behavior.
get_core_schema	kind: "source" | "stream"	Returns the authoritative DSL schema definition from StreamWright core validation rules.
validate_source_config	source_dir_or_yaml: str	Validates a source directory (containing source.yaml and streams/*.yaml) or a single YAML file against StreamWright DSL rules.
inspect_stream_transform	sql_query: str, sample_record: dict (optional)	Executes DuckDB SQL against a sample payload to verify column projections, JSON extraction, or type casting before running in production.
get_cli_reference	command: str (optional)	Returns the authoritative reference for StreamWright CLI commands (run, validate, connectors, mcp), flags, outputs, execution recipes, and the sw alias.

---

MCP Resources Reference

StreamWright MCP provides standard resources for IDEs that support resource attachments:

URI	Content
streamwright://schema/source	Complete specification and field reference for source.yaml.
streamwright://schema/stream	Complete specification for stream definitions in streams/*.yaml.
streamwright://schema/core	Full specification of the declarative data pipeline DSL.

---

Client Configurations

MCP clients launch streamwright-mcp via standard input/output (stdio) or Server-Sent Events (sse).

Depending on how Python and packages are managed in your environment:

• Active Environment / PATH: If streamwright-mcp is in your PATH, simply use "command": "streamwright-mcp".
• Virtual Environment: If installed in a dedicated virtual environment, specify the path to the executable (e.g. "/path/to/venv/bin/streamwright-mcp"). You can find this path by activating your environment and running which streamwright-mcp (or where streamwright-mcp on Windows).
• Ephemeral Execution (uvx): Run on-demand without prior installation using "command": "uvx" with ["streamwright-mcp", "--transport", "stdio"].

1. Google Antigravity

Add the server entry to your global Antigravity MCP configuration at ~/.gemini/config/mcp_config.json:

~/.gemini/config/mcp_config.json

{
  "mcpServers": {
    "streamwright": {
      "command": "streamwright-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

Virtual Environment Path

If streamwright-mcp is installed inside a specific virtual environment:

{
  "mcpServers": {
    "streamwright": {
      "command": "/path/to/venv/bin/streamwright-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

2. Claude Desktop

Add the server to your Claude Desktop configuration file:

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

claude_desktop_config.json

{
  "mcpServers": {
    "streamwright": {
      "command": "streamwright-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

Running with uvx

To run on-demand without manual installation:

claude_desktop_config.json

{
  "mcpServers": {
    "streamwright": {
      "command": "uvx",
      "args": ["streamwright-mcp", "--transport", "stdio"]
    }
  }
}

3. Cursor

Create or edit .cursor/mcp.json in your workspace root:

.cursor/mcp.json

{
  "mcpServers": {
    "streamwright": {
      "command": "streamwright-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

4. GitHub Copilot CLI

Add the MCP server to GitHub Copilot CLI using the command line:

# When installed in active PATH
copilot mcp add --transport stdio streamwright -- streamwright-mcp

# When using a virtual environment
copilot mcp add --transport stdio streamwright -- /path/to/venv/bin/streamwright-mcp

5. Claude Code CLI

Add the MCP server to Claude Code using the command line:

# When installed in active PATH
claude mcp add streamwright -- streamwright-mcp --transport stdio

# When using a virtual environment
claude mcp add streamwright -- /path/to/venv/bin/streamwright-mcp --transport stdio

---

Running in Network / SSE Mode

If connecting from remote agents or Docker containers, launch streamwright-mcp using Server-Sent Events (SSE):

streamwright-mcp --transport sse --port 8000

The MCP endpoint will be accessible at http://localhost:8000/sse.

---

Example Prompting with MCP

Once connected to your AI agent, you can ask questions naturally:

"List all installed connectors in my environment and show me the authentication and transform contract for Google Ads."

The agent will invoke list_connectors, followed by get_connector_contract("google_ads"), and return exact configuration requirements without guessing.

"Generate a source folder for PostgreSQL pulling from the users and orders tables, shape them with DuckDB SQL, and validate the folder."

The agent will retrieve the contract, write the YAML files, call validate_source_config, and guarantee that the pipeline is syntactically sound before you run it.