# freshfilings-mcp

MCP server for [FreshFilings](https://freshfilings.dev) — gives AI agents live access to U.S. business entity data from official state filing databases.

## What it does

The U.S. has no central business registry. Each state runs its own. FreshFilings aggregates them. This MCP server exposes that data as tools any AI agent can call directly.

**Current coverage:** New York, Florida, Colorado (3M+ entities)

## Tools

| Tool | Description |
|------|-------------|
| `search_businesses` | Search for businesses by name, optionally filter by state |
| `get_business_detail` | Full record for a single entity — officers, addresses, registered agent |
| `get_new_formations` | Businesses formed since a given date, useful for sales prospecting |
| `check_usage` | Check your API key usage and remaining calls this month |

## Quickstart

**Requires a FreshFilings API key.** Get one at [freshfilings.dev](https://freshfilings.dev).

```bash
# Run directly with uvx (no install needed)
FRESHFILINGS_API_KEY=your_key uvx freshfilings-mcp
```

## Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "freshfilings": {
      "command": "uvx",
      "args": ["freshfilings-mcp"],
      "env": {
        "FRESHFILINGS_API_KEY": "your_key_here"
      }
    }
  }
}
```

## Cursor / other MCP clients

```json
{
  "mcpServers": {
    "freshfilings": {
      "command": "uvx",
      "args": ["freshfilings-mcp"],
      "env": {
        "FRESHFILINGS_API_KEY": "your_key_here"
      }
    }
  }
}
```

## Environment variables

| Variable | Required | Description |
|----------|----------|-------------|
| `FRESHFILINGS_API_KEY` | Yes | Your FreshFilings API key |
| `FRESHFILINGS_BASE_URL` | No | Override API base URL (default: `https://freshfilings.dev/api/v1`) |

## Example usage

Once connected, you can ask your AI agent things like:

- *"Is Acme Holdings LLC registered and active in New York?"*
- *"Get me all LLCs formed in Florida since January 1st"*
- *"Look up the registered agent for entity 4827193 in NY"*
- *"How many API calls do I have left this month?"*

## Getting an API key

1. Go to [freshfilings.dev](https://freshfilings.dev/#pricing)
2. Choose a plan and complete checkout
3. Key is emailed immediately — no sales call, no waiting

## License

MIT