WatchBase MCP Server
An MCP (Model Context Protocol) server providing access to the WatchBase Data Feed API for querying comprehensive watch metadata.
What is WatchBase?
WatchBase 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
Quick Start
1. Clone and Install
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):
{
"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):
{
"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
{
"id": 59,
"name": "Audemars Piguet"
}
Watch List Response
{
"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 detailscase— Case specificationsdial— Dial informationadded,modified,published— Metadata dates
For Watch Dealers
This MCP server is perfect for:
- Inventory Management — Look up reference numbers and specifications
- Price Research — Get detailed specs to compare with market prices
- Authentication — Verify reference numbers and specifications
- Content Creation — Generate accurate watch descriptions
- Customer Service — Quickly answer questions about any watch
Typical Workflow
- Search by reference number —
search_refnrwith partial ref - Get watch ID from search results
- Fetch full details —
get_watch_detailswith ID - 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 for detailed API documentation.
Development
# 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
- Check the path to
build/index.jsis correct - Restart Claude Desktop/Code
- Check logs for connection errors
License
MIT License — see LICENSE file.
Note: This MCP server is an independent project. Please refer to WatchBase Terms of Service for API usage policies.
Links
- WatchBase Data Feed — API access and pricing
- WatchBase Website — Browse the watch database
- Model Context Protocol — MCP documentation