Metadata-Version: 2.4
Name: altfinance-mcp
Version: 0.3.1
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]>=1.26.0
Requires-Dist: uvicorn>=0.30.0
Description-Content-Type: text/markdown

# ALT/FNDATA MCP Server

Connect Claude to luxury asset auction data. Query watches, handbags, and jewelry auction results 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 ALT/FNDATA 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?"
- "Show me Patek Philippe watches sold at Phillips sorted by price"
- "What jewelry sold for over $1M last year?"

## Available Tools

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

| Tool | Description | Annotations |
|------|-------------|-------------|
| `list_tables` | Lists available tables (watches, handbags, jewelry) | `readOnlyHint`, `openWorldHint` |
| `get_table_schema` | Shows column names and types for a table | `readOnlyHint`, `openWorldHint` |
| `query_table` | Queries with filters, sorting, and pagination | `readOnlyHint`, `openWorldHint` |

### 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

| Table | Description | Records |
|-------|-------------|---------|
| Watches | Luxury watch auction results from major houses | 390K+ |
| Handbags | Designer handbag auction results | 120K+ |
| Jewelry | Jewelry and gemstone auction results | 480K+ |

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

## Remote Connector (Claude.ai)

ALT/FNDATA is also available as a built-in connector in Claude. When connecting through Claude.ai, you'll be prompted to enter your ALT/FNDATA 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 ALT/FNDATA 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 ALT/FNDATA 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 ALT/FNDATA 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 ALT/FNDATA 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 ALT/FNDATA API key

## License

MIT
