Metadata-Version: 2.5
Name: altfinance-mcp
Version: 0.4.0
Summary: MCP server for querying luxury asset auction data (watches, handbags, jewelry) via the ALT/FNDATA API
Project-URL: Homepage, https://altfndata.com
Project-URL: Documentation, https://altfndata.com/docs
Project-URL: Repository, https://github.com/altfinance/altfinance-mcp
Author-email: ALT/FNDATA <support@altfndata.com>
License-Expression: MIT
License-File: LICENSE
Keywords: auctions,claude,finance,handbags,jewelry,luxury,mcp,watches
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]<2,>=1.26.0
Requires-Dist: uvicorn>=0.30.0
Description-Content-Type: text/markdown

# AltFinance MCP Server

Connect Claude to luxury asset auction data. Query watches, jewelry, loose gemstones, handbags, cars, motorcycles, aircraft, wine and whisky, fine art, works of art, design, fashion, shoes, automobilia, and books from 100+ global auction houses directly in Claude.

## Quick Start

### 1. Install

```bash
pip install altfinance-mcp
```

### 2. Get an API Key

Sign up at [altfndata.com](https://altfndata.com) to get your API key.

### 3. Configure Claude Desktop

Add to your Claude Desktop config file:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "altfinance": {
      "command": "altfinance-mcp",
      "env": {
        "ALTFINANCE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Restart Claude Desktop after adding the configuration.

### 3b. Or Configure Claude Code

```bash
claude mcp add altfinance -- altfinance-mcp
```

Set the env var before launching:
```bash
export ALTFINANCE_API_KEY="your-api-key-here"
```

## What You Can Ask Claude

Once configured, ask Claude questions like:

- "What tables are available in the AltFinance database?"
- "Show me the schema for the watches table"
- "Find the top 10 most expensive Rolex watches sold after 2020"
- "How many Hermes handbags were sold by Christie's?"
- "Give me market stats for Patek Philippe watches sold at Phillips"
- "How have Hermes Birkin prices moved over the last five years?"
- "Price-check a Rolex Daytona 116500 white dial"
- "Search the whole market for a Burma ruby ring over $50k"
- "What loose sapphires have sold at auction?" (uses `gems`, not `jewelry`)

## Available Tools

All 9 tools are **read-only** and annotated with `readOnlyHint: true`. No data is modified by any tool.

| Tool | Description |
|------|-------------|
| `list_tables` | Lists the 15 available tables with live descriptions and column counts |
| `get_table_schema` | Shows column names and types for one table |
| `query_table` | Queries a table with filters, sorting, field selection, and pagination |
| `market_stats` | Realized-price summary for a table or filtered segment: count of sales, median, 25th/75th percentiles, average, min/max, sale-date span, and top vendors by volume |
| `price_trend` | How realized prices moved over time, bucketed by year, quarter, or month (count, median, average per period) |
| `price_check` | Fair-value range for a single item from comparable sales, with source links. Live comp categories: handbags, watches, cars |
| `search` | Whole-market keyword search across every category at once, merged by realized price. With no category it fans out across all 15 tables |
| `market_index` | Precomputed model-level price index (low / 25th / median / 75th / high, sample size, trend) for a brand or model. Covered categories: handbags, watches, cars |
| `list_alerts` | Read-only view of price alerts, or guidance on enabling them. See "Price alerts are read-only" below |

Every tool carries `readOnlyHint` and `openWorldHint`.

### Price alerts are read-only

Price alerts belong to a signed-in AltFinance account (Cognito login), not to an API key. The MCP authenticates with an API key only, so it **cannot create or enable alerts**, and the alerts feed itself is not reachable for an API-key caller. `list_alerts` therefore either reports fired alerts (when a session makes the feed reachable) or returns guidance on setting alerts up in the app at [app.altfndata.com](https://app.altfndata.com). Alert allowance by plan: free 0, registered 1, collector 10, pro 100, included with Membership.

### Feature and plan suggestions

Some tool responses may append a single short "💡" line suggesting a complementary AltFinance product or a plan upgrade. This happens at most once per response, only at a genuine tier boundary (a table your plan does not include, or an exhausted row quota) or as a relevant feature tip, and never for unlimited or comp accounts. It never changes the data returned.

### Query Capabilities

- **Filter** by any column using operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `like`, `in`, `not_in`, `is_null`, `is_not_null`
- **Sort** by any column, ascending or descending
- **Select** specific fields to return
- **Paginate** with limit/offset (max 500 rows per request)

## Data Coverage

The database spans 15 tables. Call `list_tables` for the live set with current column counts.

| Table | Description |
|-------|-------------|
| `watches` | Luxury watch auction results |
| `handbags` | Luxury handbag auction results |
| `jewelry` | Finished jewelry, mounted pieces (rings, necklaces, bracelets, earrings) set with gemstones |
| `gems` | Loose, unmounted gemstones (single stones and parcels). Use this for gemstone valuations, not `jewelry` |
| `automobile` | Collector car auction results |
| `motorcycle` | Collector motorcycle auction results |
| `aircraft` | Aircraft auction results |
| `wine_whisky` | Wine and whisky auction results |
| `works_of_art` | Works of art with stone/jewelry relevance (jade, jadeite, diamond-set, etc.) |
| `fine_art` | Fine art auction results across all movements and periods |
| `design` | Design and decorative arts: furniture, lighting, glass, ceramics, studio/industrial design |
| `fashion` | Fashion and couture: clothing and accessories (not handbags or shoes, which have their own tables) |
| `shoes` | Footwear: designer shoes and collectible sneakers |
| `automobilia` | Automotive memorabilia, parts, signage, models and related collectibles (not the cars themselves) |
| `books` | Books, manuscripts, maps and printed material |

**`gems` vs `jewelry`:** `gems` holds LOOSE, unmounted stones (the right table for a gemstone valuation); `jewelry` holds FINISHED, mounted pieces set with stones. If one returns nothing, try the other.

Data sources include Christie's, Sotheby's, Phillips, Bonhams, Artcurial, Dorotheum, Heritage Auctions, and 100+ other auction houses worldwide.

## Remote Connector (Claude.ai)

AltFinance is also available as a built-in connector in Claude. When connecting through Claude.ai, you'll be prompted to enter your AltFinance API key via a secure OAuth flow — no local installation needed.

### Self-Hosting the Remote Server

To run the MCP server in remote (HTTP) mode:

```bash
export ALTFINANCE_TRANSPORT=streamable-http
export ALTFINANCE_ISSUER_URL=https://mcp.altfndata.com
export ALTFINANCE_RESOURCE_URL=https://mcp.altfndata.com
python -m altfinance_mcp
```

Or with Docker:

```bash
docker build -t altfinance-mcp .
docker run -p 8000:8000 \
  -e ALTFINANCE_TRANSPORT=streamable-http \
  -e ALTFINANCE_ISSUER_URL=https://mcp.altfndata.com \
  -e ALTFINANCE_RESOURCE_URL=https://mcp.altfndata.com \
  altfinance-mcp
```

The remote server exposes:
- `POST/GET/DELETE /mcp` — MCP Streamable HTTP endpoint (authenticated)
- `GET /.well-known/oauth-authorization-server` — OAuth metadata
- `POST /register` — Dynamic Client Registration
- `GET /authorize` — OAuth authorization
- `POST /token` — Token exchange
- `GET/POST /login` — API key entry form

## Environment Variables

### Local (stdio) mode

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `ALTFINANCE_API_KEY` | Yes | — | Your AltFinance API key |
| `ALTFINANCE_API_URL` | No | `https://api.altfndata.com` | API base URL |

### Remote (HTTP) mode

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `ALTFINANCE_TRANSPORT` | Yes | `stdio` | Set to `streamable-http` |
| `ALTFINANCE_API_URL` | No | `https://api.altfndata.com` | API base URL |
| `ALTFINANCE_HOST` | No | `0.0.0.0` | HTTP listen address |
| `ALTFINANCE_PORT` | No | `8000` | HTTP listen port |
| `ALTFINANCE_ISSUER_URL` | No | `http://localhost:8000` | OAuth issuer URL (your public URL) |
| `ALTFINANCE_RESOURCE_URL` | No | Same as issuer | OAuth resource server URL |

## Privacy Policy

This MCP server connects to the AltFinance API (`api.altfndata.com`) to retrieve auction data. The following outlines our data practices:

- **Data collection**: The server sends your API key and query parameters (table names, filters, sort options) to the AltFinance API. No personal user data is collected beyond what is required for API authentication and query execution.
- **Usage and storage**: Query data is processed in real-time and returned to the MCP client. The server does not persist, cache, or store any query results or user data locally.
- **Third-party sharing**: Data is exchanged only between the MCP client and the AltFinance API (`api.altfndata.com`). No data is shared with any other third parties.
- **Data retention**: The server is stateless. No user data or query history is retained after a session ends.
- **Contact**: For privacy inquiries, contact [support@altfndata.com](mailto:support@altfndata.com).

Full privacy policy: [https://altfndata.com/privacy-policy/](https://altfndata.com/privacy-policy/)

## Support

- **Documentation**: [https://altfndata.com/docs](https://altfndata.com/docs)
- **Email**: [support@altfndata.com](mailto:support@altfndata.com)
- **GitHub Issues**: [https://github.com/altfinance/altfinance-mcp/issues](https://github.com/altfinance/altfinance-mcp/issues)

## Requirements

- Python 3.10+
- An AltFinance API key

## License

MIT
