Letin MCP Server

letin

An MCP server that gives an AI assistant (GitHub Copilot in VS Code, Claude, …) real tools for managing Power Query (M) queries, in Excel workbooks and in Power BI projects.

Copilot in Excel / Power BI can suggest M. It cannot see how your queries depend on each other, rename one without breaking the rest, repoint forty queries at a new server, tell you which step killed query folding, put your queries in git, run a query to see what a step really returns, or check the M it just wrote against the real function library. This server does those things.

What it does

Every write snapshots first, returns a unified diff, accepts dry_run=true, and is refused if it would turn valid M into a syntax error. All edits are token-aware: a query called Sales is never confused with a column [Sales], the string "Sales", or a comment.

Sources

Every tool takes a source:

A .pbix file is refused with instructions (save as .pbip, or open it and use pbi:desktop). Desktop must be closed/reopened to pick up PBIP edits (that is how Desktop works, not a limitation of this server).

How evaluation works

evaluate_* never runs anything in your session. A private, hidden, macro-disabled Excel opens a throwaway copy of the workbook (unsaved edits included), or for non-Excel sources a blank workbook seeded with the source's queries. Your expression is wrapped in try, the outcome is serialised to JSON by M itself, landed on a scratch sheet and read back. The refresh runs in the background under a watchdog; on timeout that Excel is killed, so a credential or privacy prompt cannot hang the server. Typical cost: 7-10 s per call. Non-Excel sources are evaluated by Excel's engine: Power BI-only connectors are unavailable and credentials come from Excel's data source settings for your Windows user. ignore_privacy_levels=true turns the privacy firewall off for that one throwaway evaluation.

Install

Windows, Python 3.10+, Excel installed for workbook editing. letin is on PyPI and in the MCP Registry as io.github.S-CurveLabs/letin. The simplest way to run it is with uv, which needs no separate install step:

uvx letin

Or install it with pip install letin and run letin.

GitHub Copilot in VS Code

Run MCP: Open User Configuration from the command palette and add:

{
  "servers": {
    "letin": {
      "type": "stdio",
      "command": "uvx",
      "args": ["letin"]
    }
  }
}

Then in Copilot Chat switch to Agent mode and check that the letin tools are enabled.

Claude Code

claude mcp add letin -- uvx letin

From source

git clone https://github.com/S-CurveLabs/letin.git
cd letin
python -m venv .venv
.\.venv\Scripts\pip install -e .

Opening the clone in VS Code picks up .vscode/mcp.json, which runs that checkout with .venv\Scripts\python.exe -m letin.

Things to ask

• "List the queries in C:\Reports\Sales.xlsx and draw the dependency graph as Mermaid."
• "Lint it. Which steps are breaking query folding?"
• "Every query points at \\oldserver\finance. Move that into a parameter called SourceFolder."
• "Rename Query1 to stg_Orders everywhere."
• "In Budget, unpivot everything except Department and Account, then group by Department summing Value."
• "Export the queries to ./queries so I can commit them." / "What changed in the workbook since that export?"
• "Undo that last change."
• "What columns does Sales have after the Merged Queries step? Show me 5 rows." / "Walk me through what every step of Sales does." / "At which step does the error first appear?"
• "Write a query that pivots months into columns, validate it, run it, then save it as Sales by Month."
• "What's the signature of Table.NestedJoin? Which functions split text?"
• "Format every query in this workbook." / "What queries are in the report I have open in Power BI Desktop?"

Safety model

• Snapshots live in %LOCALAPPDATA%\letin\snapshots\<workbook>-<hash>\ (last 50 per source); override the root with LETIN_HOME.
• Formulas with unbalanced brackets or unterminated strings are rejected before they reach the host.
• Hidden Excel instances are started with AutomationSecurity = ForceDisable: workbook macros never run.
• refresh_query only works on a workbook you have open, because a hidden refresh can block forever on a credentials or privacy-level prompt.
• The server itself makes no network calls. Only evaluate_* and refresh_query run M, always in Excel's engine, which then contacts whatever data sources that M reads, exactly as a refresh in Excel would. Every other tool is static analysis.
• Evaluation happens on a throwaway copy in a separate hidden Excel, under a timeout; nothing open on your screen is modified.

Limits (v0.2)

• Evaluation needs Excel on the machine, and uses Excel's engine even for Power BI sources (see above).
• Live Power BI Desktop is read-only, and needs Windows PowerShell 5.1 (built into Windows) to drive Desktop's ADOMD client.
• Reference analysis is lexical. Names built at runtime (Expression.Evaluate, #shared) are reported, not rewritten.
• The validator knows the library of this machine's Excel; connectors that exist only in Power BI are reported as info, never as errors. Regenerate the catalog after an Office update with python scripts/build_m_library.py.
• Lint rules about folding are heuristics; confirm with View Native Query.
• model.bim is re-serialised as 2-space JSON, so the first diff can be noisy if your tool formats it differently.

Development

.\.venv\Scripts\pip install -e ".[dev]"
.\.venv\Scripts\pytest -m "not excel"   # pure tests
.\.venv\Scripts\pytest                  # also drives a real hidden Excel

Layout: m/ (lexer, structural parser, full syntax parser, validator, formatter) → graph.py lint.py refactor.py transforms.py (pure, host-agnostic) → hosts/ (Excel COM + file, PBIP/TMDL, model.bim, live Desktop, M files, folder) → evaluate.py (hidden-Excel evaluation) → server.py (MCP tools). data/m_library.json is generated by scripts/build_m_library.py.

License

MIT. See LICENSE.