Insightiq MCP server

InsightIQ: Economy Insight Assistant

InsightIQ is a local MCP server that gives an AI agent (Claude Code, Claude Desktop, or any other MCP client) the ability to look up real FRED (Federal Reserve Economic Data) series and their historical observations to answer economic questions.

The flow is:

or geteconomicdata tool) for series relevant to the user's question.

1. An agent searches FRED's live series catalog (via the searcheconomicseries

InsightIQ returns retrieved data only, it does not generate the explanation.

1. The agent fetches annual observations and units for the series it cares about.
2. The agent analyzes that data itself and answers the user's question —

Install

Published on npm as insightiq-mcp. You'll need a free FRED API key first: get one here.

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

Add that to your MCP client's config (a .mcp.json file for Claude Code, or Settings → Developer → Edit Config in Claude Desktop). See mcp/README.md for the full tool reference and per-client details.

Architecture

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

Everything runs as a single local process launched by the agent host. There is no database, no local catalog, no separate backend service, and no LLM call anywhere in InsightIQ itself — the only model doing any reasoning about the data is whichever LLM is driving the calling agent.

Tools

searcheconomicseries

Searches FRED's live series catalog. Takes queries: 1-3 concise, FRED-style keyword phrases (e.g. ["inflation", "consumer price index"]) rather than a full question — FRED's full-text search effectively requires every word in a phrase to match, so short specific phrases work far better than sentences. Returns real FRED series IDs and titles only; it never invents series IDs. Each phrase is run through a filler-word stripper before hitting FRED for exactly this reason. Optional limit (default 4) and tags/excludeTags (FRED's tag vocabulary, e.g. geography or seasonal adjustment) narrow results further.

getseriesobservations

Fetches historical annual observations and units for specific FRED series IDs. Returns raw data only — no summary or explanation is generated.

geteconomicdata

Convenience tool that chains the two above: searches for relevant series using searchQueries if given (falling back to the raw question otherwise), then fetches their observations. Still returns raw data only. Accepts the same limit/tags/excludeTags as searcheconomicseries.

listseriestags

Given a topic phrase, returns the FRED tags that actually exist among matching series with their series counts — the discovery step for using tags/excludeTags above, since FRED's tag vocabulary usually can't be guessed reliably.

Development

The following is only relevant if you want to modify this server or contribute to it — not needed to use it (see Install above for that).

and src/clients/ hold the FRED search and data-fetch logic; evals/ has the MCP-level eval suite (tool contract + retrieval recall).

• mcp/: the MCP server. src/tools/ are the exposed tools; src/services/

Prerequisites: Node.js 20 or newer, a FRED API key.

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

Create mcp/.env from mcp/.env.template:

Shortened. The full README is on GitHub.