Listriver Api MCP Server

ListRiver Business Data API

New and active U.S. businesses from official state business registries (Secretary of State filings), as JSON. New LLCs, corporations, nonprofits and partnerships, filtered by state, city, county, ZIP, NAICS industry, entity type, formation month, and whether a phone or email is on file.

• Free key: 500 records a month, no card needed: get one here
• Full documentation with a live "Try it" panel and examples in cURL, Python, JavaScript, C# and PHP: listriver.com/api-docs
• Python client: pip install listriver (source)
• OpenAPI 3 spec: openapi.yaml (import into Postman, Insomnia, Swagger UI or an AI agent)
• MCP server for Claude and other AI assistants, source in mcp/: uvx listriver-mcp

Typical uses: lead lists of brand-new businesses (formed this month), CRM enrichment, sales territory research, KYB and business verification, market sizing, and B2B prospecting by industry and place.

---

Quick start (2 minutes)

1. Create a free API account and click the link in the confirmation email.
2. On the API page, click Get my free API key and copy it.
3. Count a search (free), then pull the records:

# How many businesses formed in Miami in the last few months have a phone number? (free)
curl -H "X-Api-Key: YOUR_KEY" "https://listriver.com/api/data.ashx?action=count&states=FL&city=MIAMI&hasPhone=1&formedWithin=3"

# The first 10 of them
curl -H "X-Api-Key: YOUR_KEY" "https://listriver.com/api/data.ashx?action=records&states=FL&city=MIAMI&hasPhone=1&formedWithin=3&limit=10"

{
  "ok": true,
  "rows": [
    {
      "businessName": "ANGELI TRAVEL LLC",
      "entityType": "LIMITED LIABILITY COMPANY",
      "status": "ACTIVE",
      "formed": "2026-08",
      "registrationState": "FL",
      "stateFilingNumber": "L26000446708",
      "address": "2125 BISCAYNE BLVD, STE 204 #27572",
      "city": "MIAMI",
      "zip": "33137",
      "county": "MIAMI-DADE",
      "phone": "(786) 298-9566",
      "website": "HTTPS://ANGELITRAVELS.COM",
      "registeredAgent": "ULLOA SANCHEZ YUDELSA",
      "listriverId": "FL-L26000446708",
      "...": "35 fields in all"
    }
  ],
  "cursor": "FL.6604750",
  "resume": "FL.6604750"
}

Python

from listriver import Client

lr = Client("YOUR_KEY")
search = dict(states="FL", city="MIAMI", has_phone=True, formed_within=3)

print(lr.count(**search))                      # free
for business in lr.records(**search, max_records=100):
    print(business["businessName"], business["phone"])

More: examples/ (Python, JavaScript, curl) and the recipes (also C# and PHP).

---

MCP server (source in this repo)

This repository contains a Model Context Protocol server for ListRiver, written in Python: mcp/listriver_mcp/server.py (package mcp/, tests in mcp/tests/, MIT license). It runs over stdio and gives AI assistants (Claude Desktop, Claude Code, Cursor and other MCP clients) three tools:

The server tells the assistant to count first and to fetch only what you need.

Install from PyPI (published from this repo's mcp/ folder) and add it to Claude Desktop (Settings > Developer > Edit Config):

{
  "mcpServers": {
    "listriver": {
      "command": "uvx",
      "args": ["listriver-mcp"],
      "env": { "LISTRIVER_API_KEY": "lr_key_..." }
    }
  }
}

Or run it from source:

git clone https://github.com/ListRiver-LLC/listriver-api && cd listriver-api
pip install ./python ./mcp
LISTRIVER_API_KEY=lr_key_... listriver-mcp

# or with Docker, using the Dockerfile in this repo
docker build -t listriver-mcp .
docker run -i --rm -e LISTRIVER_API_KEY=lr_key_... listriver-mcp

Setup for other clients: mcp/README.md. Listed in the official MCP Registry as io.github.ListRiver-LLC/listriver.

---

Calls

Every call is an HTTPS GET to https://listriver.com/api/data.ashx with your key in the X-Api-Key header.

Filters

records and count take the same filters. A record must match all of them; where a filter takes several comma-separated values, any one of them matches.

Formation dates are month-level (registries publish the month), so windows are whole calendar months.

Pricing

Only records returned count, and each record counts every time it is returned: overlapping or repeated searches count again. Count first (free), save the cursor or resume position to carry on later, and use listriverId to de-duplicate. Packs and plans are on your API page. Current prices are always on listriver.com/api-docs.

Keeping a feed up to date

Every records answer includes resume: the position after the last record returned, even on the last page. Save it per state, and pass it as cursor next time to get only the businesses ListRiver has added since. See examples/python/daily_feed.py.

Sample data

sample-data/ has a small sample of recent Florida formations (CSV and JSON, no emails) so you can judge the data before signing up. It is a sample, not a full file.

Data and terms

Records come from official state business registries, with addresses standardized and contact details, NAICS codes and EINs added where available. A field is null when the state doesn't publish it or ListRiver doesn't have it; nothing is estimated. Coverage and update schedules: listriver.com/methodology.

The code in this repository is MIT-licensed. The data (including sample-data/) is covered by the ListRiver API agreement: for your own business use, not for resale, and not for credit, insurance, employment or housing decisions.

Questions: support@listriver.com