search_fred_series
Find economic time series in the FRED database by keyword search, returning popular series IDs when the exact identifier is unknown.
Instructions
Search the FRED catalog (800K+ economic time series) by keyword. Returns series IDs ranked by popularity. Use this when you don't know the exact series_id for an indicator.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search keywords (e.g. "treasury yield", "korea unemployment", "high yield spread") | |
| limit | No | Max results (default 20) |
Implementation Reference
- packages/fred/src/index.ts:106-121 (handler)Core FRED API client method that calls FRED /series/search endpoint with a query, limit, ordered by popularity descending, returning FredSearchResult[].
const searchSeries = async (query: string, limit = 20): Promise<FredSearchResult[]> => { const data = await get<{ seriess: RawSeriesEntry[] }>('/series/search', { search_text: query, limit: String(limit), order_by: 'popularity', sort_order: 'desc', }); return data.seriess.map((s) => ({ id: s.id, title: s.title, units: s.units, frequency: s.frequency, last_updated: s.last_updated, popularity: s.popularity ?? 0, })); }; - apps/mcp/src/tools/macro.ts:129-150 (handler)MCP tool handler for 'search_fred_series'. Defines tool registration, Zod schema (query string, limit number 1-100 default 20), and callback that gets FRED API key, creates client, and returns search results.
server.tool( 'search_fred_series', "Search the FRED catalog (800K+ economic time series) by keyword. Returns series IDs ranked by popularity. Use this when you don't know the exact series_id for an indicator.", { query: z .string() .describe( 'Search keywords (e.g. "treasury yield", "korea unemployment", "high yield spread")', ), limit: z.number().int().min(1).max(100).default(20).describe('Max results (default 20)'), }, async ({ query, limit }) => { const apiKey = getFredKey(); if (!apiKey) return err('FRED API key not set. Run: firma config set fred-key <your-key>'); try { const client = createFredClient(apiKey); const results = await client.searchSeries(query, limit); return ok(results); } catch (e) { return err(e instanceof Error ? e.message : 'Failed to search FRED'); } }, - packages/fred/src/types.ts:18-25 (schema)Type definition for search results returned by the FRED search operation.
export type FredSearchResult = { id: string; title: string; units: string; frequency: string; last_updated: string; popularity: number; }; - apps/mcp/src/index.ts:24-24 (registration)Top-level registration call that wires the search_fred_series tool (among others) into the MCP server.
registerMacroTools(server); - apps/mcp/src/tools/macro.ts:132-139 (schema)Zod input schema for the search_fred_series tool: a required query string and optional limit (1-100, default 20).
{ query: z .string() .describe( 'Search keywords (e.g. "treasury yield", "korea unemployment", "high yield spread")', ), limit: z.number().int().min(1).max(100).default(20).describe('Max results (default 20)'), },