govauctions-mcp

# GovAuctions MCP server

Agent-callable tools for **government-surplus auction data**: search live listings,
pull real sold-price comps, and get a 0–100 Flip Score resale signal — the same
engine behind [GovAuctions](https://govauctions.app).

It exposes four read-only tools:

| Tool | What it does |
|------|--------------|
| `search_listings` | Search live surplus auction listings (facts only). Filter by country, state, category, source, keyword, price. |
| `get_listing` | Fetch one listing by id (live or archived). |
| `get_sold_comps` | Sold-price range (25th / median / 75th percentile) for a described item, from past government auctions. |
| `get_flip_score` | Flip Score resale signal for a listing: estimated value, effective bid, and discount. |

All tools are read-only. Get an API key (free tier available) at
**https://govauctions.app/developers**.

## Use it (two ways)

### 1. Hosted (remote) — no install

Point any client that speaks remote MCP at the hosted Streamable HTTP endpoint:

```json
{
  "mcpServers": {
    "govauctions": { "url": "https://govauctions.app/api/mcp" }
  }
}
```

`get_sold_comps` is open on the hosted endpoint; the other three tools read your
key from the request. See the [developer docs](https://govauctions.app/developers).

### 2. Local (stdio) — this file

A dependency-free Node wrapper (Node 18+) over the REST Data API. Download
[`govauctions-mcp.mjs`](./govauctions-mcp.mjs) and add it to your client:

```json
{
  "mcpServers": {
    "govauctions": {
      "command": "node",
      "args": ["/absolute/path/to/govauctions-mcp.mjs"],
      "env": { "GOVAUCTIONS_API_KEY": "gak_your_key" }
    }
  }
}
```

Config (env):

- `GOVAUCTIONS_API_KEY` — required. Your key from https://govauctions.app/developers/keys
- `GOVAUCTIONS_API_BASE` — optional. Defaults to `https://govauctions.app/api/v1`

## API

The tools wrap the public REST Data API. OpenAPI spec:
https://govauctions.app/api/v1/openapi.json

## License

MIT — see [LICENSE](./LICENSE).