sqlmesh-mcp

MCP server exposing a SQLMesh project to LLM agents: model metadata, plan previews, column-level lineage, audits/tests, and environment diffs.

Not officially affiliated with SQLMesh or Tobiko Data.

Why

SQLMesh's standout feature is column-level lineage, which is exactly the kind of question an agent is good at answering interactively ("where does revenue in finance.daily_summary come from?") that a CLI isn't. As of writing, the only prior MCP server for SQLMesh (sherman94062/sqlmesh-mcp) is a small unmaintained side project — this one aims to be documented, tested, and kept current with SQLMesh's API.

Install

pip install sqlmesh-mcp

Usage

Point it at a SQLMesh project directory:

{
  "mcpServers": {
    "sqlmesh": {
      "command": "sqlmesh-mcp",
      "env": { "SQLMESH_PROJECT_PATH": "/path/to/your/sqlmesh/project" }
    }
  }
}

Example

Calling list_models against examples/demo_project (a stock sqlmesh init duckdb project) returns:

[
  {
    "name": "sqlmesh_example.full_model",
    "kind": "FULL",
    "description": null,
    "owner": null,
    "tags": [],
    "columns": { "item_id": "INT", "num_orders": "BIGINT" }
  },
  {
    "name": "sqlmesh_example.incremental_model",
    "kind": "INCREMENTAL_BY_TIME_RANGE",
    "description": null,
    "owner": null,
    "tags": [],
    "columns": { "id": "INT", "item_id": "INT", "event_date": "DATE" }
  },
  {
    "name": "sqlmesh_example.seed_model",
    "kind": "SEED",
    "description": null,
    "owner": null,
    "tags": [],
    "columns": { "id": "INT", "item_id": "INT", "event_date": "DATE" }
  }
]

From there, lineage("sqlmesh_example.full_model", "num_orders") traces that column back to incremental_model.id — the kind of question this server exists for.

Tools

apply_plan and run are the two tools that change real data in whatever warehouse the project points at. Every other tool is read-only. Both are marked destructiveHint/non-readOnlyHint in their MCP tool annotations so clients can warn a user before calling them.

One server process is scoped to a single SQLMesh project, set once via SQLMESH_PROJECT_PATH (the context is cached for the life of the process). Point a client at multiple projects by running multiple server instances, one per SQLMESH_PROJECT_PATH.

Not yet covered

SQLMesh's table_diff and format commands aren't exposed as tools yet — planned, not forgotten. Contributions welcome.

Testing

See TEST_CASES.md for a plain-English index of every test case and what it covers, including a real bug the protocol-level tests caught that direct function-call tests couldn't (tool errors getting silently replaced with a generic message unless raised as the SDK's own ToolError).

License

MIT