Metadata-Version: 2.4
Name: acsearch-mcp
Version: 0.1.1
Summary: MCP server for acsearch.info — ancient coin auction archive with 16M+ lots
Project-URL: Homepage, https://github.com/wushanyun64/acsearch-mcp
Project-URL: Repository, https://github.com/wushanyun64/acsearch-mcp
Project-URL: Issues, https://github.com/wushanyun64/acsearch-mcp/issues
Author: Jason Sun
License: MIT
License-File: LICENSE
Keywords: acsearch,ancient-coins,auction-archive,coin-auction,market-research,mcp,numismatics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Indexing/Search
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.28.0
Requires-Dist: lxml>=5.0.0
Description-Content-Type: text/markdown

<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
