{
  "markdown": "# Gretl MCP\n\n[![npm version](https://img.shields.io/npm/v/gretl-mcp?label=npm)](https://www.npmjs.com/package/gretl-mcp)\n[![GitHub stars](https://img.shields.io/github/stars/OndrejLapes/GretlMCP?style=social)](https://github.com/OndrejLapes/GretlMCP)\n\nBuilt for AI agents: run Hansl/Gretl workflows, get graph screenshots, and view\ncalculations in the real Gretl GUI.\n\nIt lets MCP clients run Gretl/Hansl scripts, raw Gretl command lines, existing\n`.inp` files, package operations, package builds, help lookups, dataset\nsummaries, and OLS models. The generic `gretl_run_script` tool is the main path\nfor prompt-generated Gretl workflows: the client writes Hansl from the user's\nrequest, runs it through Gretl, and returns Gretl's output plus generated\nartifacts.\n\nKeywords: Claude Gretl, MCP econometrics, Hansl AI, Gretl GUI automation.\n\n## Key Features\n\n- Scriptable Gretl control through `gretlcli`.\n- GUI-first workflow tools that launch `gretl.exe` and fail if the GUI did not open.\n- Capability discovery for Gretl commands, functions, and package commands.\n- Generic execution tools for full Hansl scripts, command lists, and local\n  `.inp` script files.\n- Package tools for `pkg` and `makepkg` workflows from the Gretl Function\n  Package Guide.\n- High-level tools for version checks, command help, dataset summaries, and OLS.\n- Stdio transport, compatible with common MCP clients.\n- Safe defaults for arbitrary scripts, with documented escape hatches.\n\n## Requirements\n\n- Node.js 20 or newer.\n- Gretl 2026b or newer with `gretlcli` available.\n- An MCP client that supports stdio servers.\n\n## Getting Started\n\nOne-command install (after npm publish):\n\n```powershell\nnpx -y gretl-mcp@latest --version\n```\n\nLocal install from GitHub:\n\n```powershell\ngit clone https://github.com/OndrejLapes/GretlMCP.git\ncd GretlMCP\nnpm install\nnpm run build\n```\n\nThen point your MCP client at the built server:\n\n```json\n{\n  \"mcpServers\": {\n    \"gretl\": {\n      \"command\": \"node\",\n      \"args\": [\"C:\\\\Users\\\\YOUR_USER\\\\GretlMCP\\\\dist\\\\index.js\"],\n      \"env\": {\n        \"GRETL_CLI\": \"C:\\\\Users\\\\YOUR_USER\\\\tools\\\\gretl\\\\gretlcli.exe\",\n        \"GRETL_GUI\": \"C:\\\\Users\\\\YOUR_USER\\\\tools\\\\gretl\\\\gretl.exe\"\n      }\n    }\n  }\n}\n```\n\n## Visual Walkthrough\n\nForecast output example (actual vs forecast):\n\n![Forecast actual vs forecast](docs/assets/forecast_actual_vs_forecast.png)\n\nForecast error panel:\n\n![Forecast errors](docs/assets/forecast_errors.png)\n\n## Install Gretl\n\n### Windows\n\nDownload Gretl from the official page:\nhttps://gretl.sourceforge.net/win32/\n\nFor a no-admin setup, extract the zip archive to:\n\n```text\nC:\\Users\\YOUR_USER\\tools\\gretl\n```\n\nVerify:\n\n```powershell\n& C:\\Users\\YOUR_USER\\tools\\gretl\\gretlcli.exe --version\n```\n\n### macOS\n\nInstall via Homebrew (if available on your setup) or the Gretl project site:\n\n```bash\nbrew install gretl\ngretlcli --version\n```\n\n### Linux\n\nInstall from your distro packages, then verify:\n\n```bash\nsudo apt-get install gretl    # Debian/Ubuntu example\ngretlcli --version\n```\n\n## MCP Client Config\n\nUse this JSON config for stdio MCP clients:\n\n```json\n{\n  \"mcpServers\": {\n    \"gretl\": {\n      \"command\": \"node\",\n      \"args\": [\"C:\\\\Users\\\\YOUR_USER\\\\GretlMCP\\\\dist\\\\index.js\"],\n      \"env\": {\n        \"GRETL_CLI\": \"C:\\\\Users\\\\YOUR_USER\\\\tools\\\\gretl\\\\gretlcli.exe\",\n        \"GRETL_GUI\": \"C:\\\\Users\\\\YOUR_USER\\\\tools\\\\gretl\\\\gretl.exe\"\n      }\n    }\n  }\n}\n```\n\nAfter npm publication, the standard MCP config is:\n\n```json\n{\n  \"mcpServers\": {\n    \"gretl\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"gretl-mcp@latest\"],\n      \"env\": {\n        \"GRETL_CLI\": \"C:\\\\Users\\\\YOUR_USER\\\\tools\\\\gretl\\\\gretlcli.exe\",\n        \"GRETL_GUI\": \"C:\\\\Users\\\\YOUR_USER\\\\tools\\\\gretl\\\\gretl.exe\"\n      }\n    }\n  }\n}\n```\n\n## Client Setup\n\n### Claude Code\n\nLocal GitHub build:\n\n```powershell\nclaude mcp add gretl node C:\\Users\\YOUR_USER\\GretlMCP\\dist\\index.js\n```\n\nnpm install path:\n\n```powershell\nclaude mcp add gretl npx -y gretl-mcp@latest\n```\n\n### Codex\n\nLocal GitHub build:\n\n```toml\n[mcp_servers.gretl]\ncommand = \"node\"\nargs = [\"C:\\\\Users\\\\YOUR_USER\\\\GretlMCP\\\\dist\\\\index.js\"]\n\n[mcp_servers.gretl.env]\nGRETL_CLI = \"C:\\\\Users\\\\YOUR_USER\\\\tools\\\\gretl\\\\gretlcli.exe\"\nGRETL_GUI = \"C:\\\\Users\\\\YOUR_USER\\\\tools\\\\gretl\\\\gretl.exe\"\n```\n\nnpm install path:\n\n```toml\n[mcp_servers.gretl]\ncommand = \"npx\"\nargs = [\"-y\", \"gretl-mcp@latest\"]\n\n[mcp_servers.gretl.env]\nGRETL_CLI = \"C:\\\\Users\\\\YOUR_USER\\\\tools\\\\gretl\\\\gretlcli.exe\"\nGRETL_GUI = \"C:\\\\Users\\\\YOUR_USER\\\\tools\\\\gretl\\\\gretl.exe\"\n```\n\n### Cursor, Windsurf, Cline, and similar clients\n\nUse the local JSON config above. If the client asks for a command and args\nseparately, use:\n\n```text\ncommand: node\nargs: C:\\Users\\YOUR_USER\\GretlMCP\\dist\\index.js\n```\n\n### VS Code\n\n```powershell\ncode --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\\\"}}\"\n```\n\n## Try It Quickly\n\nAsk your agent:\n\n```text\nRun a Gretl forecasting dashboard with AR, ARIMA, and VAR. Save plots and compare RMSE/MAE.\n```\n\nThe MCP response includes generated artifact paths, workspace/script paths, and\nGUI launch details.\n\n## Configuration\n\n`gretl-mcp` supports environment variables and CLI flags.\n\nEnvironment variables:\n\n- `GRETL_CLI`: optional path to `gretlcli` or `gretlcli.exe`.\n- `GRETL_GUI`: optional path to `gretl` or `gretl.exe`.\n- `GRETLMCP_WORKSPACE_DIR`: optional directory for Gretl run workspaces.\n- `GRETLMCP_OPEN_GUI`: set to `false` to stop tools from opening Gretl windows by default.\n- `GRETLMCP_REQUIRE_GUI`: set to `false` to allow CLI-only success when GUI opening is disabled or unavailable.\n- `GRETLMCP_ENFORCE_GUI_ONLY`: set to `true` to reject any headless workflow request.\n\nCLI options:\n\n```powershell\ngretl-mcp --gretl-cli C:\\Users\\YOUR_USER\\tools\\gretl\\gretlcli.exe\ngretl-mcp --gretl-gui C:\\Users\\YOUR_USER\\tools\\gretl\\gretl.exe\ngretl-mcp --workspace C:\\Users\\YOUR_USER\\gretl-mcp-runs\ngretl-mcp --enforce-gui-only\ngretl-mcp --allow-headless\ngretl-mcp --help\ngretl-mcp --version\n```\n\n## Tools\n\n- `gretl_version`: checks Gretl availability.\n- `gretl_gui_version`: checks Gretl GUI availability.\n- `gretl_gui_launch`: launches the visible Gretl desktop GUI.\n- `gretl_capabilities`: lists installed Gretl commands, functions, and package help.\n- `gretl_run_script`: runs a Gretl/Hansl script and requires GUI opening by default.\n- `gretl_run_commands`: runs raw Gretl command lines and requires GUI opening by default.\n- `gretl_run_script_file`: runs an existing local `.inp` file and requires GUI opening by default.\n- `gretl_package`: runs native `pkg` actions such as install, query, run-sample, unload, remove, and index.\n- `gretl_make_package`: builds `.gfn` or `.zip` function packages with `makepkg`.\n- `gretl_help`: returns Gretl help for a command.\n- `gretl_dataset_summary`: opens a local dataset, returns summary statistics, and requires GUI opening by default.\n- `gretl_ols`: opens a local dataset, estimates an OLS model, and requires GUI opening by default.\n\n## Safety\n\n`gretl_run_script`, `gretl_run_commands`, and `gretl_run_script_file` default to\n`safeMode: true`, which blocks common shell-like commands and absolute file\nreads/writes. This is a guardrail, not a complete sandbox. Use `safeMode: false`\nonly for trusted local work.\n\nDataset helper tools reject URLs and require paths to existing local files.\n\n## Examples\n\n- `examples/homework-variance-ftest.inp`: Gretl script for a homework-style\n  F test with critical-value and p-value calculations.\n- `examples/forecasting-dashboard.inp`: Macro forecasting dashboard with AR,\n  ARIMA, VAR, forecast plots, and an RMSE/MAE comparison table.\n- `examples/specification-curve-analysis.inp`: 32-model robustness sweep for an\n  education coefficient with curve, confidence bands, and histogram plots.\n\n## Use Cases\n\n- Econometrics teaching aid with visible Gretl GUI workflows.\n- Textbook replication and assignment automation.\n- Forecasting dashboards (AR/ARIMA/VAR) with artifact outputs.\n- Monte Carlo and stress-testing workflows for research.\n- Reproducible research pipelines via saved scripts and Gretl `.inp` files.\n\n## GUI Mode\n\nBy default, the workflow tools open their generated Hansl script in the real\nGretl desktop app while also returning structured MCP output. More importantly,\nthey now treat GUI opening as required outside CI. If the Gretl window does not\nopen, the tool returns `ok: false` even when the CLI script itself succeeded.\n\nSet `displayInGretl: false` and `requireGui: false` on a tool call, or set\n`GRETLMCP_OPEN_GUI=false` together with `GRETLMCP_REQUIRE_GUI=false`, to allow\nCLI-only automation.\n\nFor clients that should never bypass the desktop app, set\n`GRETLMCP_ENFORCE_GUI_ONLY=true` or launch the server with `--enforce-gui-only`.\nIn that mode, the workflow tools reject `displayInGretl: false` and\n`requireGui: false` instead of honoring them.\n\n`gretl_gui_launch` can also be called directly. It starts the real Gretl desktop\napplication, opens a local dataset/script file, or writes a prompted Hansl script\nand launches Gretl with `--run`.\n\nThis is not full click-by-click GUI control by itself. If you want the agent to\nobserve screenshots, click menus, and make choices exactly like a human, the MCP\nclient also needs desktop automation or computer-use capability. Gretl MCP now\nprovides the Gretl-side launch surface for that workflow.\n\n## Local Development\n\n```powershell\nnpm install\nnpm run typecheck\nnpm test\nnpm run build\nnpm run smoke\nnpm run stress\n```\n\n`npm run stress` drives the built MCP server through broader prompt-style\nworkflows: macro forecasting, structural breaks, Monte Carlo simulation,\ntextbook replication, diagnostic automation, NLS, mixed-frequency compaction,\npanel models, GARCH graphs, IV simulation, and a reproducible project. The\nforeign-language stress case is dependency-gated and requires a real Python,\nRscript, or Octave executable on `PATH`.\n\nTo surface stress outputs for docs or QA snapshots:\n\n```powershell\nnpm run stress\n```\n\nThen inspect the reported workspace for generated graphs/tables.\n\nRun the built server:\n\n```powershell\nnode dist/index.js\n```\n\n## Publishing\n\nThis project is structured for GitHub, npm, and MCP Registry metadata:\n\n- GitHub hosts source code, issues, docs, releases, and CI.\n- npm will provide the easiest user install path after publication.\n- `server.json` is included for registry publish.\n\nBefore publishing to npm or the MCP Registry, review `docs/publishing.md`.\n\n## Community\n\nIssues and pull requests are welcome. See `CONTRIBUTING.md` for contribution\nflow and expectations.\n",
  "bytes": 10751,
  "sha": "2d183e59954905c46f7b90f2a0bfbbfc0d3172c548bc5ab4572c995cadd43ef2",
  "repo_slug": "ondrejlapes/gretlmcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ondrejlapes_gretl_mcp_3f506cf9/readme"
}