Gretl MCP

Gretl MCP

专为 AI Agent 打造：运行 Hansl/Gretl 工作流、获取图表截图，并在真正的 Gretl GUI 中查看计算结果。

它允许 MCP 客户端运行 Gretl/Hansl 脚本、原始 Gretl 命令行、现有 .inp 文件、软件包操作、软件包构建、帮助查询、数据集摘要和 OLS 模型。通用的 gretl_run_script 工具是执行由提示词生成的 Gretl 工作流的主要途径：客户端根据用户请求编写 Hansl，然后通过 Gretl 运行，并返回 Gretl 的输出及生成的文件。

关键词：Claude Gretl、MCP 计量经济学、Hansl AI、Gretl GUI 自动化。

主要功能

• 通过 gretlcli 对 Gretl 进行脚本化控制。
• 以 GUI 为先的工作流工具：启动 gretl.exe，若 GUI 未打开则报错。
• 探索 Gretl 命令、函数和软件包命令的功能。
• 通用执行工具，可运行完整 Hansl 脚本、命令列表和本地 .inp 脚本文件。
• 提供软件包工具，用于执行 Gretl Function Package Guide 中的 pkg 和 makepkg 工作流。
• 提供高级工具，用于检查版本、查询命令帮助、生成数据集摘要和运行 OLS。
• 使用 Stdio 传输，兼容常见的 MCP 客户端。
• 对任意脚本采用安全默认设置，并提供文档说明的绕过方式。

要求

• Node.js 20 或更高版本。
• Gretl 2026b 或更高版本，且 gretlcli 可用。
• 支持 Stdio 服务的 MCP 客户端。

快速开始

一键安装（发布到 npm 后）：

npx -y gretl-mcp@latest --version

从 GitHub 本地安装：

git clone https://github.com/OndrejLapes/GretlMCP.git
cd GretlMCP
npm install
npm run build

然后将 MCP 客户端指向构建好的服务：

{
  "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"
      }
    }
  }
}

图示

预测输出示例（实际值与预测值）：

预测误差面板：

安装 Gretl

Windows

从官方页面下载 Gretl： https://gretl.sourceforge.net/win32/

若要免管理员权限安装，请将 zip 压缩包解压到：

C:\Users\YOUR_USER\tools\gretl

验证：

& C:\Users\YOUR_USER\tools\gretl\gretlcli.exe --version

macOS

通过 Homebrew 安装（若你的环境支持），或从 Gretl 项目网站安装：

brew install gretl
gretlcli --version

Linux

从发行版软件包安装，然后验证：

sudo apt-get install gretl    # Debian/Ubuntu example
gretlcli --version

MCP 客户端配置

stdio MCP 客户端请使用此 JSON 配置：

{
  "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"
      }
    }
  }
}

发布到 npm 后，标准 MCP 配置如下：

{
  "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"
      }
    }
  }
}

客户端设置

Claude Code

本地 GitHub 构建：

claude mcp add gretl node C:\Users\YOUR_USER\GretlMCP\dist\index.js

npm 安装方式：

claude mcp add gretl npx -y gretl-mcp@latest

Codex

本地 GitHub 构建：

[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 安装方式：

[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 及类似客户端

使用上方的本地 JSON 配置。如果客户端要求分别填写命令和参数，请使用：

command: node
args: C:\Users\YOUR_USER\GretlMCP\dist\index.js

VS 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\"}}"

快速试用

向你的 Agent 提问：

Run a Gretl forecasting dashboard with AR, ARIMA, and VAR. Save plots and compare RMSE/MAE.

MCP 响应包含生成文件的路径、工作区/脚本路径以及 GUI 启动详情。

配置

gretl-mcp 支持环境变量和 CLI 标志。

环境变量：

• GRETL_CLI：gretlcli 或 gretlcli.exe 的可选路径。
• GRETL_GUI：gretl 或 gretl.exe 的可选路径。
• GRETLMCP_WORKSPACE_DIR：Gretl 运行工作区的可选目录。
• GRETLMCP_OPEN_GUI：设为 false，以阻止工具默认打开 Gretl 窗口。
• GRETLMCP_REQUIRE_GUI：设为 false，在 GUI 打开功能已禁用或不可用时，允许仅通过 CLI 成功运行。
• GRETLMCP_ENFORCE_GUI_ONLY：设为 true，拒绝任何无头工作流请求。

CLI 选项：

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 --version

工具

• gretl_version：检查 Gretl 是否可用。
• gretl_gui_version：检查 Gretl GUI 是否可用。
• gretl_gui_launch：启动可见的 Gretl 桌面 GUI。
• gretl_capabilities：列出已安装的 Gretl 命令、函数和软件包帮助。
• gretl_run_script：运行 Gretl/Hansl 脚本，默认要求打开 GUI。
• gretl_run_commands：运行原始 Gretl 命令行，默认要求打开 GUI。
• gretl_run_script_file：运行现有的本地 .inp 文件，默认要求打开 GUI。
• gretl_package：运行原生 pkg 操作，例如 install、query、run-sample、unload、remove 和 index。
• gretl_make_package：使用 makepkg 构建 .gfn 或 .zip 函数软件包。
• gretl_help：返回 Gretl 命令的帮助信息。
• gretl_dataset_summary：打开本地数据集并返回汇总统计量，默认要求打开 GUI。
• gretl_ols：打开本地数据集并估计 OLS 模型，默认要求打开 GUI。

安全

gretl_run_script、gretl_run_commands 和 gretl_run_script_file 默认将 safeMode: true，这会阻止常见的类 Shell 命令以及绝对路径文件的读取和写入。 这是一项防护措施，并非完整的沙箱。仅在可信的本地工作中使用 safeMode: false。

数据集辅助工具会拒绝 URL，并要求使用指向现有本地文件的路径。

示例

• examples/homework-variance-ftest.inp：用于作业风格 F 检验的 Gretl 脚本，包含临界值和 p 值计算。
• examples/forecasting-dashboard.inp：宏观预测仪表板，包含 AR、ARIMA、VAR、预测图以及 RMSE/MAE 对比表。
• examples/specification-curve-analysis.inp：针对教育系数的 32 模型稳健性扫描，包含曲线、置信带和直方图。

使用场景

• 配合可见 Gretl GUI 工作流的计量经济学教学辅助工具。
• 教科书复现和作业自动化。
• 带有产物输出的预测仪表板（AR/ARIMA/VAR）。
• 用于研究的蒙特卡洛和压力测试工作流。
• 通过保存的脚本和 Gretl .inp 文件构建可复现的研究流水线。

GUI 模式

默认情况下，工作流工具会在返回结构化 MCP 输出的同时，在真实的 Gretl 桌面应用中打开生成的 Hansl 脚本。更重要的是，在 CI 环境之外， 现在会将打开 GUI 视为必需步骤。如果 Gretl 窗口未打开，即使 CLI 脚本本身 运行成功，工具也会返回 ok: false。

在工具调用中设置 displayInGretl: false 和 requireGui: false，或同时设置 GRETLMCP_OPEN_GUI=false 与 GRETLMCP_REQUIRE_GUI=false，即可允许 仅使用 CLI 进行自动化。

对于绝不应绕过桌面应用的客户端，可设置 GRETLMCP_ENFORCE_GUI_ONLY=true，或使用 --enforce-gui-only 启动服务。 在此模式下，工作流工具会拒绝 displayInGretl: false 和 requireGui: false，而不会遵从这些设置。

也可以直接调用 gretl_gui_launch。它会启动真实的 Gretl 桌面应用， 打开本地数据集或脚本文件，或者写入提示词指定的 Hansl 脚本并使用 --run 启动 Gretl。

此功能本身并不提供完整的逐步 GUI 操作。如果希望 Agent 像人类一样查看 屏幕截图、点击菜单并做出选择，MCP 客户端还需要具备桌面自动化或计算机使用 能力。Gretl MCP 现在为此工作流提供 Gretl 侧的启动接口。

本地开发

npm install
npm run typecheck
npm test
npm run build
npm run smoke
npm run stress

npm run stress 会通过更广泛的提示词风格工作流运行已构建的 MCP 服务，包括宏观预测、结构突变、蒙特卡洛模拟、教科书复现、诊断自动化、NLS、混合频率压缩、面板模型、GARCH 图表、IV 模拟以及可复现项目。外语压力测试用例受依赖条件限制，需要 PATH 中存在真实的 Python、Rscript 或 Octave 可执行文件。

如需为文档或 QA 快照展示压力测试输出：

npm run stress

然后检查报告的工作区，查看生成的图表和表格。

运行已构建的服务：

node dist/index.js

发布

本项目针对 GitHub、npm 和 MCP Registry 元数据进行了结构设计：

• GitHub 用于托管源代码、问题、文档、发布版本和 CI。
• 发布后，npm 将提供最简便的用户安装方式。
• 项目包含用于发布到注册表的 server.json。

在发布到 npm 或 MCP Registry 之前，请查看 docs/publishing.md。

社区

欢迎提交问题和拉取请求。贡献流程和要求请参阅 CONTRIBUTING.md。