watchbase

WatchBase MCP Server exposes a set of tools to query the WatchBase Data Feed API and retrieve detailed watch metadata. The server supports six tools: search, search_refnr, list_brands, list_families, list_watches, and get_watch_details. You can use these tools through any MCP client that adheres to the MCP specification by specifying the tool name and the required parameters (for example q for search, brand_id for lists, id for details). The server requires a WatchBase API key to access the upstream data, which you provide via the WATCHBASE_API_KEY environment variable. Typical usage involves looking up reference numbers, browsing brands and families, and then fetching full watch specifications for a selected watch, including technical details like caliber, case, and dial information.

Prerequisites:

• Node.js 18 or newer
• npm (comes with Node.js)

1. Clone the repository

   • git clone https://github.com/watchdealer-pavel/watchbase-mcp-server.git
   • cd watchbase-mcp-server

2. Install dependencies

   • npm install

3. Configure environment and build

   • Create a .env file or export the API key in your environment: export WATCHBASE_API_KEY=your-api-key-here
   • Build the server (if a build step is defined in the project): npm run build

4. Run the MCP server

   • Run directly with Node (as configured in mcp_config): node build/index.js
   • Optional: use a process manager or start script if provided by the project

5. Verify

   • Ensure the server starts without errors and is reachable by your MCP client

Notes:

• The server exposes the WatchBase data via the MCP interface; the API key is required for upstream access.
• If you plan to run in a container or different environment, ensure the WATCHBASE_API_KEY is provided to the runtime.

Tips and common issues:

• Ensure WATCHBASE_API_KEY is present in the environment; without it, API requests will fail.
• If you modify the code and rely on live rebuilding, use npm run dev for automatic rebuilds (watch mode).
• When deploying, consider using a process manager (e.g., PM2) and set env vars securely.
• If the MCP client fails to detect the server, confirm that the build/index.js path in mcp_config matches your runtime output and that the server process is actually running.
• The API may have rate limits or require whitelisting; monitor API usage and keys in WatchBase dashboard.
• The list_watches tool supports optional filters like updated_since to enable incremental sync of large inventories.