Gretl MCP

Gretl MCP

AI エージェント向けに構築されています。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 制御。
• gretl.exe を起動し、GUI が開かなかった場合は失敗する、GUI 優先のワークフローツール。
• Gretl のコマンド、関数、パッケージコマンドの機能検出。
• Hansl スクリプト全体、コマンドリスト、ローカルの .inp スクリプトファイルを実行する汎用ツール。
• Gretl Function Package Guide に基づく pkg と makepkg のワークフロー向けパッケージツール。
• バージョン確認、コマンドヘルプ、データセットの要約、OLS 向けの高水準ツール。
• 一般的な MCP クライアントと互換性のある Stdio トランスポート。
• 任意のスクリプトに対する安全なデフォルト設定と、文書化された回避手段。

要件

• Node.js 20 以降。
• gretlcli が利用可能な Gretl 2026b 以降。
• 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\"}}"

すぐに試す

エージェントに次のように依頼します：

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：install、query、run-sample、unload、remove、index などのネイティブな pkg アクションを実行します。
• 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 になっており、一般的なシェル形式のコマンドと絶対パスを使ったファイルの 読み書きをブロックします。これは安全対策であり、完全なサンドボックスではありません。信頼できる ローカル環境でのみ safeMode: false を使用してください。

データセット用ヘルパーツールは URL を拒否し、既存のローカルファイルへのパスを必須とします。

例

• examples/homework-variance-ftest.inp：臨界値と p 値の計算を含む、宿題形式の F 検定用 Gretl スクリプトです。
• examples/forecasting-dashboard.inp：AR、ARIMA、VAR、予測プロット、RMSE/MAE 比較表を含むマクロ予測ダッシュボードです。
• examples/specification-curve-analysis.inp：曲線、信頼帯、ヒストグラムのプロットを用いた、教育係数の 32 モデルによるロバスト性分析です。

ユースケース

• Gretl GUI を表示するワークフローを使った計量経済学の教育支援。
• 教科書の再現と課題の自動化。
• アーティファクト出力を伴う予測ダッシュボード（AR/ARIMA/VAR）。
• 研究向けのモンテカルロ法およびストレステストのワークフロー。
• 保存済みスクリプトと Gretl .inp ファイルによる再現可能な研究パイプライン。

GUI モード

デフォルトでは、ワークフローツールは生成した Hansl スクリプトを実際の Gretl デスクトップアプリで開くと同時に、構造化された MCP 出力も返します。さらに重要な点として、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 をクリック単位で完全に操作できるわけではありません。エージェントにスクリーンショットを確認させ、メニューをクリックし、人間と同じように選択させたい場合は、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 では、ソースコード、Issue、ドキュメント、リリース、CI を管理しています。
• 公開後は、npm がユーザーにとって最も簡単なインストール方法になります。
• レジストリへの公開用に server.json が含まれています。

npm または MCP Registry に公開する前に、docs/publishing.md を確認してください。

コミュニティ

Issue やプルリクエストを歓迎します。貢献の流れと期待事項については、CONTRIBUTING.md を参照してください。