# GovAuctions MCP server

[**GovAuctions.app**](https://govauctions.app) is a free public site for finding
government surplus auctions: live listings from GSA and other government sellers,
alongside what comparable lots actually sold for. This repo is its MCP server, a
second front door onto the same data for agents and code.

Agent-callable tools for **government-surplus auction data**: search live listings,
pull real sold-price comps from 170,000+ closed government auctions in the US, UK,
Canada and Australia, and get a 0–100 Flip Score resale signal, from the same
engine behind the site.

## Tools

Eight tools on the hosted server, all read-only. The local npm package exposes
the first four.

| Tool | What it does |
|------|--------------|
| `search_listings` | Search live GSA federal-surplus listings (facts only). Filter by state, category, keyword, price. |
| `get_listing` | Fetch one live GSA listing by id. |
| `get_sold_comps` | Sold-price range (25th / median / 75th percentile) for a described item, across the US, UK, CA or AU government-surplus market. |
| `get_flip_score` | Flip Score resale signal for a listing: estimated value, effective bid, and discount. |
| `get_sold_history` | The individual archived sales behind a comp number. |
| `get_price_trend` | Month-by-month sold-price trend for a described item. |
| `get_comp_coverage` | What can and cannot be priced, by category and market. |
| `get_api_usage` | Your key's usage against its monthly allowance. |

Get an API key (free tier available) at
**https://govauctions.app/developers**.

## Use it (two ways)

### 1. Hosted (remote), no install. Recommended.

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

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

Claude Code:

```sh
claude mcp add --transport http govauctions https://govauctions.app/api/mcp \
  --header "Authorization: Bearer gak_YOUR_KEY"
```

`get_sold_comps` answers on the hosted endpoint with no key at all; the other
tools read your key from the request. See the
[developer docs](https://govauctions.app/developers).

### 2. Local (stdio) via npx

For clients that cannot add a remote MCP URL. A dependency-free Node wrapper
(Node 18+) over the REST Data API, published to npm as
[`govauctions-mcp`](https://www.npmjs.com/package/govauctions-mcp):

```json
{
  "mcpServers": {
    "govauctions": {
      "command": "npx",
      "args": ["-y", "govauctions-mcp"],
      "env": { "GOVAUCTIONS_API_KEY": "gak_your_key" }
    }
  }
}
```

Or download [`govauctions-mcp.mjs`](./govauctions-mcp.mjs) and run it with
`node /absolute/path/to/govauctions-mcp.mjs`.

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`

The local wrapper forwards every call to the REST API, so unlike the hosted
server it needs a key for every tool, including `get_sold_comps`.

## API

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

## License

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