FDIC BankFind MCP Server

Instructions

Implementation Reference

• src/tools/financials.ts:101-138 (handler)

  The handler function for fdic_search_financials tool, which queries the FDIC financials endpoint, formats the results, and handles pagination.

  async ({ cert, repdte, ...params }) => {
    try {
      const response = await queryEndpoint(ENDPOINTS.FINANCIALS, {
        ...params,
        filters: buildFilterString({
          cert,
          dateField: "REPDTE",
          dateValue: repdte,
          rawFilters: params.filters,
        }),
      });
      const records = extractRecords(response);
      const pagination = buildPaginationInfo(
        response.meta.total,
        params.offset ?? 0,
        records.length,
      );
      const output = { ...pagination, financials: records };
      const text = truncateIfNeeded(
        formatSearchResultText("financial records", records, pagination, [
          "CERT",
          "NAME",
          "REPDTE",
          "ASSET",
          "DEP",
          "NETINC",
        ]),
        CHARACTER_LIMIT,
        "Request fewer fields, narrow your filters, or paginate with limit/offset.",
      );
      return {
        content: [{ type: "text", text }],
        structuredContent: output,
      };
    } catch (err) {
      return formatToolError(err);
    }
  },

• src/tools/financials.ts:54-100 (registration)

  The tool registration for fdic_search_financials, including its metadata, description, input schema, and handler.

    server.registerTool(
      "fdic_search_financials",
      {
        title: "Search Institution Financial Data",
        description: `Search quarterly financial (Call Report) data for FDIC-insured institutions. Covers over 1,100 financial variables reported quarterly.
  
  Returns balance sheet, income statement, capital, and performance ratio data from FDIC Call Reports.
  
  Common filter examples:
    - Financials for a specific bank: CERT:3511
    - By report date: REPDTE:20231231
    - High-profit banks in Q4 2023: REPDTE:20231231 AND ROA:[1.5 TO *]
    - Large banks most recent: ASSET:[10000000 TO *]
    - Negative net income: NETINC:[* TO 0]
  
  Key returned fields:
    - CERT: FDIC Certificate Number
    - REPDTE: Report Date — the last day of the quarterly reporting period (YYYYMMDD)
    - ASSET: Total assets ($thousands)
    - DEP: Total deposits ($thousands)
    - DEPDOM: Domestic deposits ($thousands)
    - INTINC: Total interest income ($thousands)
    - EINTEXP: Total interest expense ($thousands)
    - NETINC: Net income ($thousands)
    - ROA: Return on assets (%)
    - ROE: Return on equity (%)
    - NETNIM: Net interest margin (%)
  
  Args:
    - cert (number, optional): Filter by institution CERT number
    - repdte (string, optional): Report Date in YYYYMMDD format (quarter-end dates: 0331, 0630, 0930, 1231)
    - filters (string, optional): Additional ElasticSearch query filters
    - fields (string, optional): Comma-separated field names (the full set has 1,100+ fields)
    - limit (number): Records to return (default: 20)
    - offset (number): Pagination offset (default: 0)
    - sort_by (string, optional): Field to sort by
    - sort_order ('ASC'|'DESC'): Sort direction (default: 'DESC' recommended for most recent first)
  
  Prefer concise human-readable summaries or tables when answering users. Structured fields are available for totals, pagination, and quarterly financial records.`,
        inputSchema: FinancialQuerySchema,
        annotations: {
          readOnlyHint: true,
          destructiveHint: false,
          idempotentHint: true,
          openWorldHint: true,
        },
      },

• src/tools/financials.ts:15-36 (schema)

  The input schema validation for the fdic_search_financials tool using Zod.

  const FinancialQuerySchema = CommonQuerySchema.extend({
    sort_order: z
      .enum(["ASC", "DESC"])
      .default("DESC")
      .describe(
        "Sort direction: DESC (descending, default for most recent first) or ASC (ascending)",
      ),
    cert: z
      .number()
      .int()
      .positive()
      .optional()
      .describe(
        "Filter by FDIC Certificate Number to get financials for a specific institution",
      ),
    repdte: z
      .string()
      .optional()
      .describe(
        "Filter by Report Date (REPDTE) in YYYYMMDD format. FDIC data is published quarterly on call report dates: March 31, June 30, September 30, and December 31. Example: 20231231 for Q4 2023. If omitted, returns all available dates (sorted most recent first by default).",
      ),
  });