insightiq

InsightIQ：経済分析アシスタント

InsightIQ は、AI エージェント（Claude Code、Claude Desktop、またはその他の MCP クライアント）が実際の FRED（米国連邦準備制度経済データ）の系列とその過去の観測値を検索し、経済に関する質問に回答できるようにするローカルの MCP サーバーです。

処理の流れは次のとおりです。

1. エージェントは、ユーザーの質問に関連する系列を FRED の最新の系列カタログから検索します（search_economic_series または get_economic_data ツールを使用）。
2. エージェントは、必要な系列の年間観測値と単位を取得します。
3. エージェントはそのデータを自ら分析し、ユーザーの質問に回答します。InsightIQ が返すのは取得したデータのみで、説明は生成しません。

インストール

npm で insightiq-mcp として公開されています。まず、無料の FRED API キーが必要です。こちらから取得してください。

{
  "mcpServers": {
    "insightiq": {
      "command": "npx",
      "args": ["-y", "insightiq-mcp"],
      "env": {
        "FRED_API_KEY": "your_fred_api_key_here"
      }
    }
  }
}

MCP クライアントの設定に追加してください（Claude Code の .mcp.json ファイル、または Claude Desktop の「Settings → Developer → Edit Config」）。ツールの全リファレンスとクライアントごとの詳細については、mcp/README.md を参照してください。

アーキテクチャ

flowchart TD
  agent[Agent / MCP Client] -->|Tool calls, stdio| mcp[InsightIQ MCP Server]

  mcp -->|Search phrases| fredSearch[FRED series/search]
  fredSearch -->|Real FRED series IDs| mcp

  mcp -->|Series IDs| fredApi[FRED API]
  fredApi -->|Annual observations and metadata| mcp

  mcp -->|Raw retrieved data| agent

すべての処理は、エージェントホストによって起動される単一のローカルプロセスで実行されます。データベースもローカルカタログも独立したバックエンドサービスもなく、InsightIQ 自体が LLM を呼び出すこともありません。データについて推論を行うモデルは、呼び出し元のエージェントを駆動する LLM だけです。

ツール

search_economic_series

FRED の最新の系列カタログを検索します。queries として、質問文全体ではなく、FRED 形式の簡潔なキーワード句を 1～3 個指定します（例：["inflation", "consumer price index"]）。FRED の全文検索では、句中のすべての語が一致する必要があるため、短く具体的な句のほうが文よりもはるかに効果的です。実在する FRED の系列 ID とタイトルのみを返し、系列 ID を捏造することはありません。このため、FRED に送信する前に各句から不要語を除去します。省略可能な limit（既定値は 4）と tags／excludeTags（FRED のタグ語彙。地理や季節調整など）を指定すると、結果をさらに絞り込めます。

get_series_observations

指定した FRED の系列 ID について、過去の年間観測値と単位を取得します。未加工のデータのみを返し、要約や説明は生成しません。

get_economic_data

上記 2 つのツールを連携させる便利なツールです。指定されている場合は searchQueries を使用して関連系列を検索し（それ以外の場合は元の question を使用）、その後、観測値を取得します。こちらも未加工のデータのみを返します。search_economic_series と同じ limit／tags／excludeTags を受け付けます。

list_series_tags

トピックの句を指定すると、一致する系列に実際に存在する FRED のタグと、それぞれの系列数を返します。FRED のタグ語彙は通常、正確に推測するのが難しいため、上記の tags／excludeTags を利用する前の調査手順として使います。

---

開発

以下は、このサーバーを変更または開発に協力する場合にのみ関係する内容であり、利用するだけであれば必要ありません（利用方法については、上記の インストール を参照してください）。

• mcp/：MCP サーバー。src/tools/ には公開されるツール、src/services/ と src/clients/ には FRED の検索およびデータ取得ロジック、evals/ には MCP レベルの評価スイート（ツールの契約と検索再現率）が含まれています。

前提条件：Node.js 20 以降、FRED API キー。

git clone https://github.com/ravi-p-k-1/InsightIQ.git
cd InsightIQ/mcp
npm install

mcp/.env.template から mcp/.env を作成します。

FRED_API_KEY=your_fred_api_key_here

直接実行して起動することを確認します。

npm start

リポジトリのルートには、Claude Code をローカルのチェックアウトに向けるプロジェクトスコープの .mcp.json があります（リポジトリのルートを開くと自動的に読み込まれ、初回使用時には承認が必要です）。新しいバージョンを公開する前に変更をテストするのに便利です。

検証

GitHub Actions は、main へのプッシュ時とプルリクエスト時に CI を実行し、依存関係をインストールして構文をチェックします。FRED は呼び出しません。

cd mcp
find src evals -name "*.js" -print0 | xargs -0 -n1 node --check

個別のユニットテストスイートはありません。正確性と品質は、実際のクライアントを実際のサーバーにプロセス内で接続し、エージェントとまったく同じ方法で動作させる MCP レベルの評価を通じて検証します。これらの評価では稼働中の FRED API を呼び出すため、CI ではなく手動で実行します。

cd mcp
npm run eval:contract          # tool inventory, schema/error-path, happy-path checks
npm run eval:retrieval         # retrieval recall floor (single raw question)
npm run eval:retrieval:smart   # retrieval recall ceiling (curated query plans)

eval:retrieval は、クエリインテリジェンスを使わない場合の基準値（現在の質問セットでは 45.3%）を測定します。eval:retrieval:smart は、評価時に稼働中の LLM 呼び出しを必要とせず、有能なエージェントが選ぶような質問ごとの検索フレーズ／タグを記録したセットを再生します（62.4%）。各評価のチェック内容については、mcp/README.md を参照してください。