<p align="center">
  <img src="https://img.shields.io/pypi/v/acsearch-mcp?label=PyPI&color=blue" alt="PyPI">
  <img src="https://img.shields.io/pypi/pyversions/acsearch-mcp?label=Python" alt="Python">
  <img src="https://img.shields.io/github/license/wushanyun64/acsearch-mcp?label=License" alt="License">
</p>

# acsearch-mcp

MCP server for [acsearch.info](https://www.acsearch.info) — the world's largest ancient coin auction archive, with over 16 million lots from 475 auction houses spanning 20+ years.

Give your AI agent the ability to search auction records, retrieve lot details with specs and references, analyze price history, and find comparable sales — all through acsearch.info's Premium database.

Framework-agnostic: works with any MCP-compatible client including Hermes Agent, Claude Desktop, Claude Code, Cursor, and Continue.dev.

## Quick Start

```bash
uvx acsearch-mcp --transport stdio
```

Requires an [acsearch.info Premium account](https://www.acsearch.info/subscribe.html) (€85/year) for price data. Set your credentials:

```bash
export ACSEARCH_USERNAME="your_username"
export ACSEARCH_PASSWORD="***..."
```

Cookies are cached to `~/.acsearch_cookies.json` after first login — no repeated authentication on every tool call.

## Tools

| Tool | Description |
|---|---|
| `search` | Full-text Boolean search across 16M+ auction lots |
| `get_lot` | Full lot details: description, specs, references, provenance |
| `price_history` | Year-by-year price analysis for market research and valuation |
| `find_comparables` | Recent comparable auction results sorted by date |

### Search Syntax

acsearch.info uses Boolean full-text search:

| Operator | Example | Effect |
|---|---|---|
| `*` (wildcard) | `Philip*` | Matches Philip, Philippe, Philippus |
| `"..."` (phrase) | `"Philip II tetradrachm"` | Exact phrase match |
| `-` (exclude) | `-bronze` | Exclude results containing the word |
| `(...)` (group) | `(tetradrachm drachm)` | Match either term |

Examples: `"Philip II tetradrachm"`, `Alexander* stater -bronze`, `cistophorus Ephes*`

## Client Configuration

### Hermes Agent

```yaml
mcp_servers:
  acsearch:
    command: uvx
    args:
      - acsearch-mcp
      - --transport
      - stdio
    env:
      ACSEARCH_USERNAME: your_username
      ACSEARCH_PASSWORD: ***
```

Restart: `hermes gateway restart` or `/reset` in CLI.

### Claude Desktop

```json
{
  "mcpServers": {
    "acsearch": {
      "command": "uvx",
      "args": ["acsearch-mcp", "--transport", "stdio"],
      "env": {
        "ACSEARCH_USERNAME": "your_username",
        "ACSEARCH_PASSWORD": "your_password"
      }
    }
  }
}
```

### Any MCP Client (Generic)

```bash
uvx acsearch-mcp --transport stdio
```

With `ACSEARCH_USERNAME` and `ACSEARCH_PASSWORD` set in the environment.

### HTTP Mode

For remote or networked clients:

```bash
uvx acsearch-mcp --transport http --host 0.0.0.0 --port 8001
```

Connect to `http://host:8001/mcp`.

## From Source

```bash
git clone https://github.com/wushanyun64/acsearch-mcp.git
cd acsearch-mcp
uv sync
uv run acsearch-mcp --transport stdio
```

## How It Works

acsearch.info embeds all search results as structured JSON in a `<script>` tag:

```javascript
acsearch.initSearchResults = [
  { "id": "2581457", "title": "Heritage Auctions, Auction 3041, Lot 32015",
    "description": "MACEDONIAN KINGDOM. Philip II...",
    "date": "13.08.2015", "price": "6'250 USD", "image": "https://..." }
];
```

The parser extracts this JSON directly — no fragile HTML scraping needed. The client authenticates with your Premium credentials, maintains a cookie-backed session, and enforces polite rate limiting (2 seconds between requests).

## Limitations

- Descriptions are capped at 350 characters by acsearch.info. The full catalog text is available on the original auction house page (linked in the `link` field of lot details).
- Prices require a Premium account.

## License

MIT © 2026 Jason Sun