# WatchBase MCP Server
[](https://nodejs.org)
[](https://opensource.org/licenses/MIT)
An MCP (Model Context Protocol) server providing access to the [WatchBase Data Feed API](https://watchbase.com/data-feed) for querying comprehensive watch metadata.
## What is WatchBase?
[WatchBase](https://watchbase.com) is a comprehensive watch database containing detailed information about luxury watches, including:
- **280+ brands** (Rolex, Patek Philippe, Audemars Piguet, etc.)
- **Thousands of watch families/collections**
- **Technical specifications** (case size, movement, complications, etc.)
- **Reference numbers** for precise identification
## Features
This MCP server provides 6 tools for querying the WatchBase API:
| Tool | Description | Required Params |
|------|-------------|-----------------|
| `search` | Search by brand, family, watch name, or reference number (whole words) | `q` |
| `search_refnr` | Search by reference number (partial matches allowed) | `q` |
| `list_brands` | Get all watch brands in the database | — |
| `list_families` | Get all families/collections for a brand | `brand_id` |
| `list_watches` | Get watches for a brand/family (with optional date filter) | `brand_id` |
| `get_watch_details` | Get full specifications for a specific watch | `id` |
## Prerequisites
- **Node.js 18+** (including Node.js 25)
- **WatchBase API Key** — [Request access here](https://watchbase.com/data-feed)
## Quick Start
### 1. Clone and Install
```bash
git clone https://github.com/watchdealer-pavel/watchbase-mcp-server.git
cd watchbase-mcp-server
npm install
```
### 2. Configure Your MCP Client
Add to your MCP client configuration:
**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"watchbase": {
"command": "node",
"args": ["/path/to/watchbase-mcp-server/build/index.js"],
"env": {
"WATCHBASE_API_KEY": "your-api-key-here"
}
}
}
}
```
**Claude Code** (`.mcp.json` in your project):
```json
{
"mcpServers": {
"watchbase": {
"command": "node",
"args": ["/path/to/watchbase-mcp-server/build/index.js"],
"env": {
"WATCHBASE_API_KEY": "your-api-key-here"
}
}
}
}
```
### 3. Restart Your MCP Client
Restart Claude Desktop or Claude Code to load the new MCP server.
## Usage Examples
### Search for a Watch
```
Search for "Royal Oak" watches
→ Uses: search tool with q="Royal Oak"
```
### Search by Reference Number
```
Find watches with reference number starting with "15500"
→ Uses: search_refnr tool with q="15500"
```
### Browse Brands and Families
```
List all Rolex families
→ Uses: list_brands to find Rolex ID, then list_families with brand_id
```
### Get Watch Specifications
```
Get full details for watch ID 12345
→ Uses: get_watch_details tool with id=12345
```
## API Response Examples
### Brand Object
```json
{
"id": 59,
"name": "Audemars Piguet"
}
```
### Watch List Response
```json
{
"id": 11702,
"refnr": "15500ST.OO.1220ST.01",
"name": "Royal Oak",
"brand": { "id": 59, "name": "Audemars Piguet" },
"family": { "id": 234, "name": "Royal Oak" },
"thumb": "https://cdn.watchbase.com/watch/medium/...",
"updated": "2024-01-15"
}
```
### Watch Details Response
Includes all fields plus:
- `caliber` — Movement details
- `case` — Case specifications
- `dial` — Dial information
- `added`, `modified`, `published` — Metadata dates
## For Watch Dealers
This MCP server is perfect for:
1. **Inventory Management** — Look up reference numbers and specifications
2. **Price Research** — Get detailed specs to compare with market prices
3. **Authentication** — Verify reference numbers and specifications
4. **Content Creation** — Generate accurate watch descriptions
5. **Customer Service** — Quickly answer questions about any watch
### Typical Workflow
1. **Search by reference number** — `search_refnr` with partial ref
2. **Get watch ID** from search results
3. **Fetch full details** — `get_watch_details` with ID
4. **Use specifications** for listings, comparisons, or research
### Incremental Sync for Large Inventories
Use `list_watches` with `updated_since` parameter to sync only changed records:
```
list_watches with brand_id=59, updated_since="2024-01-01"
→ Returns only watches updated after Jan 1, 2024
```
## API Documentation
See [watchbase_api_reference.md](./watchbase_api_reference.md) for detailed API documentation.
## Development
```bash
# Watch mode (auto-rebuild on changes)
npm run dev
# Manual build
npm run build
# Run the server directly
npm start
```
## Troubleshooting
### "WATCHBASE_API_KEY environment variable is required"
Make sure you've added the `WATCHBASE_API_KEY` to your MCP client's `env` configuration.
### "WatchBase API error: Invalid or unauthorized API key"
Your API key may be invalid or expired. Contact WatchBase support.
### Server not appearing in Claude
1. Check the path to `build/index.js` is correct
2. Restart Claude Desktop/Code
3. Check logs for connection errors
## License
MIT License — see [LICENSE](LICENSE) file.
**Note:** This MCP server is an independent project. Please refer to [WatchBase Terms of Service](https://watchbase.com/terms) for API usage policies.
## Links
- [WatchBase Data Feed](https://watchbase.com/data-feed) — API access and pricing
- [WatchBase Website](https://watchbase.com) — Browse the watch database
- [Model Context Protocol](https://modelcontextprotocol.io) — MCP documentation
