Gretl MCP
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., "@Gretl MCP run OLS on auto dataset and show coefficients"
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.
Gretl MCP
Built for AI agents: run Hansl/Gretl workflows, get graph screenshots, and view calculations in the real Gretl GUI.
It lets MCP clients run Gretl/Hansl scripts, raw Gretl command lines, existing
.inp files, package operations, package builds, help lookups, dataset
summaries, and OLS models. The generic gretl_run_script tool is the main path
for prompt-generated Gretl workflows: the client writes Hansl from the user's
request, runs it through Gretl, and returns Gretl's output plus generated
artifacts.
Keywords: Claude Gretl, MCP econometrics, Hansl AI, Gretl GUI automation.
Key Features
Scriptable Gretl control through
gretlcli.GUI-first workflow tools that launch
gretl.exeand fail if the GUI did not open.Capability discovery for Gretl commands, functions, and package commands.
Generic execution tools for full Hansl scripts, command lists, and local
.inpscript files.Package tools for
pkgandmakepkgworkflows from the Gretl Function Package Guide.High-level tools for version checks, command help, dataset summaries, and OLS.
Stdio transport, compatible with common MCP clients.
Safe defaults for arbitrary scripts, with documented escape hatches.
Related MCP server: Stata MCP Server
Requirements
Node.js 20 or newer.
Gretl 2026b or newer with
gretlcliavailable.An MCP client that supports stdio servers.
Getting Started
One-command install (after npm publish):
npx -y gretl-mcp@latest --versionLocal install from GitHub:
git clone https://github.com/OndrejLapes/GretlMCP.git
cd GretlMCP
npm install
npm run buildThen point your MCP client at the built server:
{
"mcpServers": {
"gretl": {
"command": "node",
"args": ["C:\\Users\\YOUR_USER\\GretlMCP\\dist\\index.js"],
"env": {
"GRETL_CLI": "C:\\Users\\YOUR_USER\\tools\\gretl\\gretlcli.exe",
"GRETL_GUI": "C:\\Users\\YOUR_USER\\tools\\gretl\\gretl.exe"
}
}
}
}Visual Walkthrough
Forecast output example (actual vs forecast):

Forecast error panel:

Install Gretl
Windows
Download Gretl from the official page: https://gretl.sourceforge.net/win32/
For a no-admin setup, extract the zip archive to:
C:\Users\YOUR_USER\tools\gretlVerify:
& C:\Users\YOUR_USER\tools\gretl\gretlcli.exe --versionmacOS
Install via Homebrew (if available on your setup) or the Gretl project site:
brew install gretl
gretlcli --versionLinux
Install from your distro packages, then verify:
sudo apt-get install gretl # Debian/Ubuntu example
gretlcli --versionMCP Client Config
Use this JSON config for stdio MCP clients:
{
"mcpServers": {
"gretl": {
"command": "node",
"args": ["C:\\Users\\YOUR_USER\\GretlMCP\\dist\\index.js"],
"env": {
"GRETL_CLI": "C:\\Users\\YOUR_USER\\tools\\gretl\\gretlcli.exe",
"GRETL_GUI": "C:\\Users\\YOUR_USER\\tools\\gretl\\gretl.exe"
}
}
}
}After npm publication, the standard MCP config is:
{
"mcpServers": {
"gretl": {
"command": "npx",
"args": ["-y", "gretl-mcp@latest"],
"env": {
"GRETL_CLI": "C:\\Users\\YOUR_USER\\tools\\gretl\\gretlcli.exe",
"GRETL_GUI": "C:\\Users\\YOUR_USER\\tools\\gretl\\gretl.exe"
}
}
}
}Client Setup
Claude Code
Local GitHub build:
claude mcp add gretl node C:\Users\YOUR_USER\GretlMCP\dist\index.jsnpm install path:
claude mcp add gretl npx -y gretl-mcp@latestCodex
Local GitHub build:
[mcp_servers.gretl]
command = "node"
args = ["C:\\Users\\YOUR_USER\\GretlMCP\\dist\\index.js"]
[mcp_servers.gretl.env]
GRETL_CLI = "C:\\Users\\YOUR_USER\\tools\\gretl\\gretlcli.exe"
GRETL_GUI = "C:\\Users\\YOUR_USER\\tools\\gretl\\gretl.exe"npm install path:
[mcp_servers.gretl]
command = "npx"
args = ["-y", "gretl-mcp@latest"]
[mcp_servers.gretl.env]
GRETL_CLI = "C:\\Users\\YOUR_USER\\tools\\gretl\\gretlcli.exe"
GRETL_GUI = "C:\\Users\\YOUR_USER\\tools\\gretl\\gretl.exe"Cursor, Windsurf, Cline, and similar clients
Use the local JSON config above. If the client asks for a command and args separately, use:
command: node
args: C:\Users\YOUR_USER\GretlMCP\dist\index.jsVS Code
code --add-mcp "{\"name\":\"gretl\",\"command\":\"node\",\"args\":[\"C:\\\\Users\\\\YOUR_USER\\\\GretlMCP\\\\dist\\\\index.js\"],\"env\":{\"GRETL_CLI\":\"C:\\\\Users\\\\YOUR_USER\\\\tools\\\\gretl\\\\gretlcli.exe\",\"GRETL_GUI\":\"C:\\\\Users\\\\YOUR_USER\\\\tools\\\\gretl\\\\gretl.exe\"}}"Try It Quickly
Ask your agent:
Run a Gretl forecasting dashboard with AR, ARIMA, and VAR. Save plots and compare RMSE/MAE.The MCP response includes generated artifact paths, workspace/script paths, and GUI launch details.
Configuration
gretl-mcp supports environment variables and CLI flags.
Environment variables:
GRETL_CLI: optional path togretlcliorgretlcli.exe.GRETL_GUI: optional path togretlorgretl.exe.GRETLMCP_WORKSPACE_DIR: optional directory for Gretl run workspaces.GRETLMCP_OPEN_GUI: set tofalseto stop tools from opening Gretl windows by default.GRETLMCP_REQUIRE_GUI: set tofalseto allow CLI-only success when GUI opening is disabled or unavailable.GRETLMCP_ENFORCE_GUI_ONLY: set totrueto reject any headless workflow request.
CLI options:
gretl-mcp --gretl-cli C:\Users\YOUR_USER\tools\gretl\gretlcli.exe
gretl-mcp --gretl-gui C:\Users\YOUR_USER\tools\gretl\gretl.exe
gretl-mcp --workspace C:\Users\YOUR_USER\gretl-mcp-runs
gretl-mcp --enforce-gui-only
gretl-mcp --allow-headless
gretl-mcp --help
gretl-mcp --versionTools
gretl_version: checks Gretl availability.gretl_gui_version: checks Gretl GUI availability.gretl_gui_launch: launches the visible Gretl desktop GUI.gretl_capabilities: lists installed Gretl commands, functions, and package help.gretl_run_script: runs a Gretl/Hansl script and requires GUI opening by default.gretl_run_commands: runs raw Gretl command lines and requires GUI opening by default.gretl_run_script_file: runs an existing local.inpfile and requires GUI opening by default.gretl_package: runs nativepkgactions such as install, query, run-sample, unload, remove, and index.gretl_make_package: builds.gfnor.zipfunction packages withmakepkg.gretl_help: returns Gretl help for a command.gretl_dataset_summary: opens a local dataset, returns summary statistics, and requires GUI opening by default.gretl_ols: opens a local dataset, estimates an OLS model, and requires GUI opening by default.
Safety
gretl_run_script, gretl_run_commands, and gretl_run_script_file default to
safeMode: true, which blocks common shell-like commands and absolute file
reads/writes. This is a guardrail, not a complete sandbox. Use safeMode: false
only for trusted local work.
Dataset helper tools reject URLs and require paths to existing local files.
Examples
examples/homework-variance-ftest.inp: Gretl script for a homework-style F test with critical-value and p-value calculations.examples/forecasting-dashboard.inp: Macro forecasting dashboard with AR, ARIMA, VAR, forecast plots, and an RMSE/MAE comparison table.examples/specification-curve-analysis.inp: 32-model robustness sweep for an education coefficient with curve, confidence bands, and histogram plots.
Use Cases
Econometrics teaching aid with visible Gretl GUI workflows.
Textbook replication and assignment automation.
Forecasting dashboards (AR/ARIMA/VAR) with artifact outputs.
Monte Carlo and stress-testing workflows for research.
Reproducible research pipelines via saved scripts and Gretl
.inpfiles.
GUI Mode
By default, the workflow tools open their generated Hansl script in the real
Gretl desktop app while also returning structured MCP output. More importantly,
they now treat GUI opening as required outside CI. If the Gretl window does not
open, the tool returns ok: false even when the CLI script itself succeeded.
Set displayInGretl: false and requireGui: false on a tool call, or set
GRETLMCP_OPEN_GUI=false together with GRETLMCP_REQUIRE_GUI=false, to allow
CLI-only automation.
For clients that should never bypass the desktop app, set
GRETLMCP_ENFORCE_GUI_ONLY=true or launch the server with --enforce-gui-only.
In that mode, the workflow tools reject displayInGretl: false and
requireGui: false instead of honoring them.
gretl_gui_launch can also be called directly. It starts the real Gretl desktop
application, opens a local dataset/script file, or writes a prompted Hansl script
and launches Gretl with --run.
This is not full click-by-click GUI control by itself. If you want the agent to observe screenshots, click menus, and make choices exactly like a human, the MCP client also needs desktop automation or computer-use capability. Gretl MCP now provides the Gretl-side launch surface for that workflow.
Local Development
npm install
npm run typecheck
npm test
npm run build
npm run smoke
npm run stressnpm run stress drives the built MCP server through broader prompt-style
workflows: macro forecasting, structural breaks, Monte Carlo simulation,
textbook replication, diagnostic automation, NLS, mixed-frequency compaction,
panel models, GARCH graphs, IV simulation, and a reproducible project. The
foreign-language stress case is dependency-gated and requires a real Python,
Rscript, or Octave executable on PATH.
To surface stress outputs for docs or QA snapshots:
npm run stressThen inspect the reported workspace for generated graphs/tables.
Run the built server:
node dist/index.jsPublishing
This project is structured for GitHub, npm, and MCP Registry metadata:
GitHub hosts source code, issues, docs, releases, and CI.
npm will provide the easiest user install path after publication.
server.jsonis included for registry publish.
Before publishing to npm or the MCP Registry, review docs/publishing.md.
Community
Issues and pull requests are welcome. See CONTRIBUTING.md for contribution
flow and expectations.
Available Tools
12 toolsgretl_capabilitiesC
List Gretl commands, built-in functions, and package-management help from the installed Gretl version.
Inputs: gretlCliPath, gretlGuiPath, displayInGretl, timeoutSeconds, +2 more.
gretl_dataset_summaryC
Open a Gretl-supported dataset file, return summary statistics, and open the same workflow in Gretl GUI by default.
Inputs: datasetPath (required), safeMode, requireGui, gretlCliPath, +4 more.
gretl_gui_launchB
Launch the visible Gretl desktop GUI, optionally opening a local dataset/script or running a provided script on startup.
Inputs: script, english, filePath, safeMode, +4 more.
gretl_gui_versionB
Return the installed Gretl GUI version by running gretl.exe --version.
Inputs: gretlGuiPath, timeoutSeconds.
gretl_helpB
Ask Gretl for command help, for example ols, summary, open, arima, or gnuplot. By default this also requires opening the help workflow in the visible Gretl GUI.
Inputs: commandName (required), requireGui, gretlCliPath, gretlGuiPath, +1 more.
gretl_make_packageC
Build a Gretl function package (.gfn or .zip) using the native makepkg command. By default this also requires opening the generated workflow in the visible Gretl GUI.
Inputs: packagePath (required), index, quiet, requireGui, +8 more.
gretl_olsB
Open a dataset, estimate an OLS model, and open the same workflow in Gretl GUI by default.
Inputs: datasetPath (required), dependentVariable (required), independentVariables (required), safeMode, +7 more.
gretl_packageB
Install, query, run samples for, unload, remove, or index Gretl function/data packages using the native pkg command. By default this also requires opening the generated workflow in the visible Gretl GUI.
Inputs: action (required), local, quiet, staging, +10 more.
gretl_run_commandsC
Run one or more raw Gretl command lines. By default this also requires opening the same workflow in the visible Gretl GUI.
Inputs: commands (required), safeMode, requireGui, gretlCliPath, +6 more.
gretl_run_scriptC
Run any Gretl/Hansl script through gretlcli. By default this also requires opening the same workflow in the visible Gretl GUI.
Inputs: script (required), safeMode, requireGui, gretlCliPath, +6 more.
gretl_run_script_fileB
Run an existing local Gretl .inp script file with gretlcli. By default this also requires opening the same workflow in the visible Gretl GUI.
Inputs: scriptPath (required), safeMode, scriptOpt, requireGui, +6 more.
gretl_versionB
Return the installed Gretl version by running gretlcli.
Inputs: gretlCliPath.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Tools are mostly distinct: version, launch, script/command execution, package management, help, data summary, and OLS. The three 'run' tools (script, commands, script_file) could cause confusion, but descriptions clarify their different inputs.
All tools share the 'gretl_' prefix, but naming patterns vary: some use verb+noun (gretl_run_script), others use noun-only (gretl_version, gretl_capabilities). While readable, there is no strict verb_noun pattern throughout.
With 12 tools, the server covers essential Gretl operations (version, GUI, script execution, packages, help, data summary, OLS) without being excessive. The count feels well-scoped for the econometrics domain.
The surface includes core tasks: version checking, GUI launching, script execution, package management, help, data summary, and OLS. While missing some advanced models or data manipulation tools, the ability to run arbitrary scripts/commands fills many gaps.
Maintenance
Related MCP Connectors
List datasets, schemas, run APL queries, and use prompts for exploration, anomalies, and monitoring.
Query and update Teable records, manage tables, and access the Teable API with AI agents.
Create AgentUI data apps: define tables, read and write records, and run programs on your data.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceProvides econometric modeling capabilities through R, enabling AI assistants to perform sophisticated analyses including linear regression, panel data models, instrumental variables regression, and diagnostic tests.217MIT
- AlicenseNot gradedqualityDmaintenanceConnects AI agents to a local Stata installation, enabling execution of Stata code, data inspection, graph generation, and result verification through natural language interactions.546 PyPI92AGPL 3.0
- FlicenseNot gradedqualityDmaintenanceEnables an agent to execute Stata do scripts or inline commands locally and retrieve structured results including status, error diagnostics, and output text for consumption by the model.1-
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to execute R code, create visualizations, analyze data, and manage packages through a local Rscript CLI.MIT