A phone verification MCP server for your AI agent

{
  "mcpServers": {
    "numberbroom": {
      "url": "https://numberbroom.com/mcp",
      "headers": { "Authorization": "Bearer nb_live_YOUR_KEY" }
    }
  }
}

{
  "mcpServers": {
    "numberbroom": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://numberbroom.com/mcp",
        "--transport", "http-only",
        "--header", "Authorization:${AUTH_HEADER}"
      ],
      "env": { "AUTH_HEADER": "Bearer nb_live_YOUR_KEY" }
    }
  }
}

{
  "inputs": [
    { "type": "promptString", "id": "numberbroom-key", "description": "NumberBroom API key (nb_live_...)", "password": true }
  ],
  "servers": {
    "numberbroom": {
      "type": "http",
      "url": "https://numberbroom.com/mcp",
      "headers": { "Authorization": "Bearer ${input:numberbroom-key}" }
    }
  }
}

{
  "mcpServers": {
    "numberbroom": {
      "serverUrl": "https://numberbroom.com/mcp",
      "headers": { "Authorization": "Bearer nb_live_YOUR_KEY" }
    }
  }
}

openapi: 3.1.0
info:
  title: NumberBroom phone verification
  version: "1.0"
servers:
  - url: https://numberbroom.com/api
paths:
  /v1/verify:
    post:
      operationId: verifyPhoneNumber
      summary: Verify one US phone number. Returns line type, carrier, activity score and known litigator status. Costs $0.20; an unparseable number or one outside the US is free.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [phone]
              properties:
                phone:
                  type: string
                  description: The number in any common US format.
      responses:
        "200":
          description: Verification result. valid is false when the input is not a US phone number, or when its carrier data is withheld (reason suppressed).
          content:
            application/json:
              schema:
                type: object
                properties:
                  phone: { type: string, description: The input as sent }
                  e164: { type: [string, "null"], description: null when the input does not parse }
                  valid: { type: boolean }
                  reason: { type: string, enum: [unparseable, not_nanp, outside_us, suppressed], description: Present only when valid is false -- why the number was not checked. suppressed is permanent -- asking again returns the same }
                  message: { type: string, description: Present only when valid is false }
                  lineType: { type: string }
                  carrier: { type: [string, "null"] }
                  isLitigator: { type: [boolean, "null"], description: true when court filings tie the number to a TCPA/FDCPA/FCRA/CFPB suit (which law is not reported and no database catches every litigator) -- null when no litigator check ran -- the carrier lookup reported the number as not valid (outcome invalid) }
                  litigator: { type: string, enum: [yes, no, not_checked], description: isLitigator as a word, for no-code tools that store and compare text (GoHighLevel, Google Sheets) -- not_checked when no litigator check ran }
                  activityScore: { type: [number, "null"], description: 0 to 100; null when the carrier data has no signal }
                  isLikelyDisconnected: { type: [boolean, "null"], description: true at an activity score of 30 or below; null when there is no score }
                  outcome: { type: string }
                  keep: { type: boolean }
                  dncEvaluated: { type: boolean }
                  charged: { type: number }
                  creditsRemaining: { type: number }
  /v1/credits:
    get:
      operationId: getCreditBalance
      summary: Remaining pre-paid balance and how many lookups it covers. Free to call.
      responses:
        "200":
          description: Balance
          content:
            application/json:
              schema:
                type: object
                properties:
                  credits: { type: number }
                  ratePerLookup: { type: number }
                  lookupsRemaining: { type: integer }
                  dailyLimit: { type: integer, description: Lookups a day this key may make when called the way this request was }
                  accountDailyLimit: { type: integer, description: Lookups a day across every key on the account }
  /v1/credits/checkout:
    post:
      operationId: createCreditCheckout
      summary: A Stripe Checkout link that adds credit to this key's account when a person pays it. Free to call.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [amount]
              properties:
                amount: { type: number, description: Dollars of credit, 10 to 5000. }
      responses:
        "200":
          description: Open url to pay. Credit lands when the payment clears.
          content:
            application/json:
              schema:
                type: object
                properties:
                  url: { type: string }
                  sessionId: { type: string }
  /v1/lists:
    post:
      operationId: createListCheckout
      summary: Send a whole list for the paid list scrub. Returns the price at list rates and a Stripe Checkout link for a person to pay; nothing is taken from API credit.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [numbers]
              properties:
                numbers:
                  type: array
                  description: Up to 10,000 phone numbers, digits and phone punctuation only.
                  items:
                    type: string
                scrubMode: { type: string, enum: [full, litigator_only] }
      responses:
        "200":
          description: The price and the link to pay it. The scrub runs once payment clears.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobId: { type: string }
                  url: { type: string }
                  rowCount: { type: integer }
                  chargedNumbers: { type: integer }
                  outsideUsRows: { type: integer, description: "Numbers outside the US (Canada, Puerto Rico, the Caribbean, overseas): not priced or scrubbed, and returned in their own file once the scrub completes" }
                  amount: { type: number }
                  scrubMode: { type: string }
                  message: { type: string }
  /v1/lists/{jobId}:
    get:
      operationId: getListStatus
      summary: Status and counts for one of this account's list scrubs, with a download link that lasts an hour once it is done.
      parameters:
        - name: jobId
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Counts appear once status is complete.
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobId: { type: string }
                  status: { type: string }
                  paid: { type: boolean }
                  scrubMode: { type: string }
                  totalNumbers: { type: [integer, "null"] }
                  amount: { type: [number, "null"] }
                  dashboardUrl: { type: string }
                  cleanCount: { type: integer }
                  litigatorCount: { type: integer }
                  voipLandlineCount: { type: integer }
                  disconnectedCount: { type: integer }
                  invalidCount: { type: integer, description: Numbers that are not valid phone numbers (removed in either scrub mode); absent on lists scrubbed before 2026-10-05 }
                  errorCount: { type: integer }
                  ownDncCount: { type: integer }
                  outsideUsRows: { type: integer, description: "Numbers outside the US, left out of the scrub and not charged; absent on lists scrubbed before 2026-10-05" }
                  downloadUrl: { type: string }
                  outsideUsDownloadUrl: { type: string, description: "Those numbers' rows, as sent, in a file of their own; present only when the list had any. Lasts as long as downloadUrl" }
                  removedDownloadUrl: { type: string, description: "The removed rows, as sent, with line_type, carrier, activity_score and removed_because, known litigators included; never a Do Not Call Registry match. Present only when rows were removed. Lasts as long as downloadUrl" }
                  litigatorDownloadUrl: { type: string, description: "The known litigator rows alone, as sent, with line_type, carrier and activity_score; present only when the list had any, and absent on lists scrubbed before 2026-10-14. Lasts as long as downloadUrl" }
                  downloadExpiresAt: { type: string }

{
  "url": "https://numberbroom.com/mcp",
  "transport": "streamable-http",
  "headers": { "Authorization": "Bearer nb_live_YOUR_KEY" }
}