sqlmesh-mcp
This MCP server exposes a SQLMesh project to LLM agents, letting them inspect models, trace lineage, preview plans, and run audits/tests — with two opt-in tools that change real data.
list_models: List all models with kind, columns, owner, and description.
get_model: Get full detail for one model (query, columns, kind, owner, tags, description).
plan: Preview what a plan against an environment would change; returns a plan_id.
apply_plan (destructive, requires confirm=true): Apply a previously previewed plan, changing real warehouse data.
lineage: Get column-level lineage showing upstream models/columns a column depends on.
run_audit: Run audits for a model (or all models) with optional start/end bounds.
run_test: Run unit tests for a model (or all tests).
diff_environment: Diff the current context against a target environment.
list_environments: List environments in the project's state.
run (destructive, requires confirm=true): Execute scheduled/due model runs for an environment, like a cron trigger.
All tools except apply_plan and run are read-only.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@sqlmesh-mcp where does revenue in finance.daily_summary come from?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
sqlmesh-mcp
MCP server exposing a SQLMesh project to LLM agents: model metadata, bounded data previews, plan previews, column-level lineage, audits/tests, environment diffs, resources, and reusable prompts.
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.
Related MCP server: dbt-assay
Install
pip install sqlmesh-mcpUsage
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
Tool | Read-only? | Description |
| Yes | List all models in the project with kind, columns, description |
| Yes | Full detail for one model |
| Yes | Direct upstream and downstream model dependencies |
| Yes | Bounded preview of current model data, capped by |
| Yes | Project, capability, transport, and safety configuration metadata |
| Yes | Start a plan preview in the background and return a job ID |
| No | Start a scheduled model run in the background; requires |
| Yes | Inspect a background plan or run job |
| No | Cancel a queued background job |
| Yes | Return transitive upstream and downstream model impact |
| Yes | Summarize environment existence, snapshots, and project drift |
| Yes | Read recent dataveil audit events without cell values |
| Yes | Preview what a plan against an environment would change |
| No | Apply a previously-previewed plan. Requires |
| Yes | Column-level lineage for a model's column |
| Yes | Run a model's audits |
| Yes | Run a model's unit tests |
| Yes | Diff two environments |
| Yes | List every environment that exists in the project's state |
| Yes | Compare two tables or environments with structured schema and row differences |
| Check only by default | Check or format SQLMesh model and audit files; writing requires |
| No | Execute scheduled/due model runs for an environment (what a cron trigger would do). Requires |
| Yes | Aggregate-only profile of a model's columns (null rates, numeric stats, generalized string format signatures). No raw rows or samples; numeric stats withheld for small or constant columns (see dataveil's Known limits). |
| Yes | Profile + a local sensitivity classification per column ( |
| No | Validate and apply a data-cleansing plan (mask/drop/impute/... from a closed, pre-tested operation vocabulary — never LLM-generated code). Requires |
| Yes | Register a plan for later approval instead of applying it directly. Validates it immediately. Only useful when |
| No* | Mark a registered plan approved by someone. Doesn't touch real data — not read-only (it mutates server-side approval state), not destructive either. |
apply_plan, run, start_run, and apply_cleansing_plan change real data in whatever warehouse the project points at. format changes project files when called with check=false, while approve_cleansing_plan and cancel_job mutate server-side state without changing warehouse data. Destructive tools are marked destructiveHint/non-readOnlyHint in their MCP annotations so clients can warn a user before calling them.
profile_model/propose_cleansing_plan/apply_cleansing_plan are powered by dataveil: profiling, PII classification, and plan execution happen locally against aggregate SQL only (never a sample of raw rows), and a cleansing plan can only reference a small, pre-tested operation vocabulary — never SQL or code an LLM wrote itself. See that project's README for its known limits. Note: apply_cleansing_plan writes directly to a model's physical snapshot table, outside SQLMesh's own state tracking — a FULL-kind model's next scheduled run/plan apply will rematerialize it and silently undo the cleansing.
MCP resources and prompts
The server also publishes MCP resources for clients that support browsing context:
Resource | Description |
| JSON metadata for every model |
| Rendered SQL and metadata for one model |
| Column-level lineage as JSON |
Reusable prompts are available as explain_model and review_plan. They guide an agent through model analysis and plan review while keeping the final mutation step explicit.
Optional plan-approval gate
By default, apply_cleansing_plan accepts a plan directly (plus confirm=true) — the same posture apply_plan/run already have. Setting DATAVEIL_REQUIRE_PLAN_APPROVAL=true adds a second, independent gate for cleansing plans specifically: apply_cleansing_plan then refuses a plan passed directly and instead requires a plan_id from a plan that was register_cleansing_plan'd and then approve_cleansing_plan'd — by a different call, potentially a different reviewer. confirm=true is still required on top of that approval, not instead of it. A plan is discarded from the registry once applied, so it can't be replayed. Off by default; turn it on once this touches anything with real compliance stakes.
Every call to these three tools is appended to a local JSON-lines audit log (<project>/.dataveil/audit.jsonl by default; override with DATAVEIL_AUDIT_LOG_PATH) — who/what/when, enough to reconstruct what happened without re-running anything, never a literal cell value.
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.
Safety and transports
Set SQLMESH_ALLOWED_ENVIRONMENTS=prod,staging to restrict plan, run, diff, and table-diff calls to an environment allowlist. When set, mutation calls must include an explicit environment. SQLMESH_MAX_RESULT_ROWS defaults to 100 and caps both data previews and table-diff samples. SQLMESH_PLAN_TTL_SECONDS defaults to 900, and SQLMESH_PLAN_CACHE_SIZE defaults to 100; cached plans expire and are bound to the configured project path. Set SQLMESH_READ_ONLY=true to disable warehouse, file, and approval-state mutations. Mutating tools still require their individual confirm=true gates.
fetch_model_data masks columns whose names suggest email, phone, SSN, social-security, or address data. Set SQLMESH_PREVIEW_COLUMNS to a comma-separated column allowlist, or pass columns per call. Unmasked values require the explicit SQLMESH_ALLOW_UNMASKED_PREVIEW=true opt-in and every preview is audit logged.
stdio remains the default transport. For a networked MCP client, run Streamable HTTP with:
MCP_TRANSPORT=streamable-http \
SQLMESH_PROJECT_PATH=/path/to/project \
MCP_HOST=127.0.0.1 MCP_PORT=8000 \
sqlmesh-mcpThe endpoint is available at http://127.0.0.1:8000/mcp by default. Set MCP_AUTH_TOKEN to protect HTTP requests with Authorization: Bearer <token>; non-loopback binding is refused unless a token is configured. Use TLS or an authenticated reverse proxy for production deployment.
For named clients and least-privilege access, use MCP_AUTH_TOKENS with a JSON object. Supported scopes are read, mutate, approve, write, and operate:
MCP_AUTH_TOKENS='{"analyst":{"token":"read-secret","scopes":["read"]},"deployer":{"token":"deploy-secret","scopes":["read","mutate","operate"]}}' \
MCP_TRANSPORT=streamable-http sqlmesh-mcpEach client may also include an expires_at Unix timestamp. MCP_AUTH_TOKEN remains supported as a legacy full-scope token. Authenticated client IDs are included in dataveil audit details.
Approval-gated cleansing plans are persisted at <project>/.dataveil/approvals.json with restrictive file permissions. Override the location with DATAVEIL_APPROVALS_PATH when the project filesystem is not durable.
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
Available Tools
27 toolsapply_cleansing_planADestructive
Validate and apply a data-cleansing plan. THIS CHANGES REAL DATA in the model's current physical snapshot table. Requires confirm=true.
Default mode: pass plan directly, built from propose_cleansing_plan's
output -- validated against the operation vocabulary and the model's
schema before any step runs, same as always.
If this server requires plan approval (DATAVEIL_REQUIRE_PLAN_APPROVAL=
true): pass plan_id instead, from a plan that was registered
(register_cleansing_plan) and then approved (approve_cleansing_plan) by
someone else. confirm=true is still required on top of that approval,
not instead of it.
Note: this writes directly to the model's physical table, outside SQLMesh's own state tracking. A FULL-kind model is fully rematerialized on its next scheduled run/plan apply, which will silently undo the cleansing -- it was never folded into the model's SQL definition. Re-apply after any such rerun if the cleansing still applies.
Inputs: model_name (required), plan, confirm, plan_id.
apply_planADestructive
Apply a previously-previewed plan. THIS CHANGES REAL DATA in the target warehouse.
Requires confirm=true. plan_id must come from a plan() call in this same session -- plans aren't kept across server restarts.
Inputs: plan_id (required), confirm.
approve_cleansing_planA
Mark a plan registered via register_cleansing_plan as approved.
This only records who approved it -- apply_cleansing_plan still requires confirm=true on top of this. Approval and confirm=true are two separate gates, not a substitute for each other.
Inputs: plan_id (required), approved_by (required).
audit_historyBRead-only
Return recent dataveil audit events without exposing cell values.
Inputs: limit. Returns: result
cancel_jobA
Cancel a queued job. Running SQLMesh operations cannot be interrupted safely.
Inputs: job_id (required).
diff_environmentARead-only
Diff the current context against a target environment.
Inputs: environment (required).
environment_healthBRead-only
Summarize environment existence, snapshots, and current project drift.
Inputs: environment (required).
fetch_model_dataARead-only
Fetch a bounded, optionally column-filtered preview of model data.
Inputs: model_name (required), limit, columns, mask_sensitive.
formatA
Check or format SQLMesh model and audit files.
The default check mode is read-only. Writing formatted files requires confirm=true and is never performed accidentally by an agent.
Inputs: check, paths, confirm.
get_job_statusBRead-only
Return the current status and result of an asynchronous plan or run.
Inputs: job_id (required).
get_modelARead-only
Full detail for one model: rendered query, columns, kind, owner, tags, description.
Inputs: model_name (required).
get_model_dependenciesCRead-only
Return the direct upstream and downstream model dependencies.
Inputs: model_name (required).
lineageBRead-only
Column-level lineage: which upstream models/columns does this column depend on.
Inputs: column (required), model_name (required).
list_environmentsARead-only
List every environment that exists in this project's state (e.g. prod, dev, ...).
Inputs: no named parameters. Returns: result
list_modelsARead-only
List every model in the SQLMesh project with its kind, columns, owner, and description.
Inputs: no named parameters. Returns: result
model_impactBRead-only
Return all transitive upstream and downstream models affected by a change.
Inputs: model_name (required).
planARead-only
Preview what a plan against an environment would change. Does not apply anything.
Returns a plan_id -- pass it to apply_plan to actually apply this exact plan.
Inputs: environment, select_models.
profile_modelARead-only
Aggregate-only profile of a model's columns: null rates, distinct counts, numeric stats, generalized string format signatures (e.g. 'ddd-dd-dddd'). Returns no raw rows or samples; see dataveil's README for its known limits.
The model must already be applied (see plan/apply_plan) -- dataveil reads from its current physical snapshot table.
Inputs: model_name (required).
propose_cleansing_planARead-only
Everything an agent needs to propose a data-cleansing plan for a model: the aggregate-only profile, a local sensitivity classification per column (PII:EMAIL, PII:SSN, PII:PHONE, ... or "none", each with a match_rate), and the closed operation vocabulary apply_cleansing_plan will accept.
This tool does not call an LLM or propose a plan itself -- it's the documented contract an agent (you) reasons over to build one. A plan is a list of {"operation", "column", "params", "rationale"} objects; "operation" must be a key in operation_vocabulary, and only the params listed for it are accepted. Pass the finished plan to apply_cleansing_plan.
Inputs: model_name (required).
register_cleansing_planARead-only
Register a cleansing plan for later approval, instead of applying it directly. Only useful when this server requires plan approval (DATAVEIL_REQUIRE_PLAN_APPROVAL=true) -- otherwise apply_cleansing_plan already accepts a plan directly and this tool isn't needed.
Validates the plan against the operation vocabulary and the model's schema immediately -- a reviewer should never approve something that would fail at execution time. Read-only: nothing is applied here.
Returns a plan_id; pass it to approve_cleansing_plan, then to apply_cleansing_plan.
Inputs: plan (required), model_name (required).
runADestructive
Execute scheduled/due model runs for an environment. THIS CHANGES REAL DATA.
Distinct from plan/apply_plan: this runs already-promoted models for their due intervals (what a cron trigger would do), rather than previewing or promoting structural changes. Requires confirm=true.
Inputs: end, start, confirm, environment.
run_auditARead-only
Run audits for a model (or all models if omitted). start/end bound the data checked.
Inputs: end, start, model_name.
run_testARead-only
Run unit tests for a model (or all tests if omitted).
Inputs: model_name.
server_infoARead-only
Return server, project, safety, and capability metadata.
Inputs: no named parameters.
start_planCRead-only
Start a plan preview in the background and return a job ID.
Inputs: environment, select_models.
start_runCDestructive
Start a scheduled model run in the background. Requires confirm=true.
Inputs: end, start, confirm, environment.
table_diffBRead-only
Compare two tables or environments and return structured schema/row differences.
When comparing environments, pass select_models to choose the models to compare. SQLMesh's console output is suppressed because MCP clients receive the JSON result.
Inputs: source (required), target (required), on, limit, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 27 tools
Several tools have overlapping intent: plan vs start_plan and run vs start_run are synchronous/async variants of the same operation, while get_model_dependencies, model_impact, and lineage all cover dependency graphs, and plan/diff_environment/table_diff all compare state. The detailed descriptions do explicitly explain the distinctions, so an agent can disambiguate, but the sync/async pairs and parallel comparison tools invite misselection.
All names are snake_case, which is consistent, but verb convention is mixed: verb_noun (get_model, run_audit, apply_plan), reversed noun_verb (table_diff vs diff_environment), and bare nouns (lineage, model_impact, server_info, environment_health) coexist. It remains readable but does not follow a single predictable pattern.
27 tools is above the comfortable range and is inflated by dual synchronous/asynchronous variants (plan/start_plan, run/start_run plus job status/cancel) and conditional tools (register/approve_cleansing_plan only matter when approval is enabled). Still, the SQLMesh domain is genuinely broad (models, plans, runs, jobs, audits, tests, environments, cleansing), so most tools earn their place.
The surface covers the domain thoroughly: model inspection/lineage, plan preview+apply, scheduled runs, job lifecycle, audits/tests, environment diff/health, formatting, and a full cleansing lifecycle. Minor gaps exist (no job listing, no model create/edit since models live as files), but these are workable.
Maintenance
Related MCP Connectors
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Project memory, documentation and controlled secret access for AI coding agents.
Gives AI agents direct access to your Sanity projects and guidance for working with them
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Related MCP Servers
AlicenseBqualityBmaintenanceEnables AI assistants to interact with Bauplan lakehouse operations, including querying tables, schema inspection, branch management, and pipeline execution.3315MIT- AlicenseNot gradedqualityBmaintenanceEnables agents to inspect dbt model semantics, retrieve contracts and lineage, and verify that edits do not change what models mean.Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to inspect schemas, walk Delta table history, run read-only DuckDB queries, and check data-quality and job-run status safely.MIT
- AlicenseAqualityCmaintenanceExposes tools that let AI coding agents browse a repo's schema snapshot of tables and columns and validate their SQL against it before running or writing it, so queries referencing invented or stale table and column names get caught and corrected up front. Provides list_tables, describe_table, search_columns, and check_sql over the same snapshot used by the CLI, hook, and CI check.41MIT