mcp-homedepot

A Model Context Protocol server for Home Depot Canada (homedepot.ca). It exposes the store's product catalogue — search, product detail, store-level stock and a store finder — to MCP clients such as Claude and Cursor.

Unofficial. This project is not affiliated with, endorsed by, or sponsored by The Home Depot. It reads publicly available endpoints of homedepot.ca for personal, noncommercial use. Respect Home Depot's terms of service and use responsibly.

Tools

Tool	Description
hd_search	Product search / listings by keyword. Returns products (SKU, name, brand, model, price, rating, online stock, URL, image), total count, facets and sort options.
hd_product	Full product card by SKU: name, brand, model, description, images, rating/reviews, warranty, categories, price, in-store stock + aisle/bay, online stock, fulfillment options.
hd_store_availability	In-store stock of a SKU across a store and its nearby stores, sorted in-stock first. Per store: name, address, phone, coordinates, stock level/status, aisle/bay, pickup status.
hd_stores	Store directory / find stores near a postal code (geocoded → distance-sorted with distanceKm), or the full national directory (~183 stores).

More tools (suggestions, categories) are planned.

hd_search

Param	Type	Default	Notes
query	string	—	Search keyword (required).
storeId	string	9999	Store id for store-specific stock/pricing.
lang	en | fr	en	Response language.
sort	relevance | price-asc | price-desc | reviewAvgRating	relevance	Sort order.
page	int	0	0-indexed page.
pageSize	int (1–60)	24	Results per page.

hd_product

Param	Type	Default	Notes
sku	string	—	Product SKU / code (required), e.g. 1001686659.
postalCode	string	—	Postal code, e.g. M5V 2T6; uses the nearest store (overrides storeId).
storeId	string	7074	Store id for store-specific price/stock/aisle. Override default with HD_DEFAULT_STORE.
lang	en | fr	en	Response language.

hd_store_availability

Param	Type	Default	Notes
sku	string	—	Product SKU / code (required).
postalCode	string	—	Postal code; nearby stores are taken around it (overrides storeId).
storeId	string	7074	Reference store; nearby stores are taken from it.
lang	en | fr	en	Response language.
limit	int (1–20)	10	Max number of stores to check.

Default store: product/availability tools default to store 7074 (Langford, BC). Set HD_DEFAULT_STORE env var, or pass storeId, to use your local store. Use hd_stores with a postal code to find the right store id.

hd_stores

Param	Type	Default	Notes
postalCode	string	—	Canadian postal code, e.g. M5V 2T6. Returns nearest stores with distanceKm.
latitude / longitude	number	—	Alternative to postalCode for proximity.
lang	en | fr	en	Response language.
limit	int (1–200)	20 / all	Max stores. Default 20 for a proximity search, all (~183) otherwise.

The store API geosorts by coordinates only, so a postal code is first geocoded via api.zippopotam.us (free, no key). distanceKm is computed locally (haversine).

How it talks to Home Depot

homedepot.ca/api/* is behind Akamai Bot Manager, which gates on both the HTTP version and the client's TLS (JA3) fingerprint. Node's native HTTP stack (fetch/undici, node:http2) gets 403. Only curl --http2 is allowlisted, so every request shells out to curl. No cookies are needed for the public search APIs.

Requirement: curl with HTTP/2 support must be on PATH (standard on macOS and most Linux distros).

Build & run

npm install
npm run build
npm start          # runs the MCP server on stdio

Quick smoke test of the search layer:

node --input-type=module -e 'import {search} from "./dist/search.js"; console.log(await search({query:"drill", pageSize:3}))'

Inspect with the MCP Inspector:

npm run inspect

Connecting a client

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json), pointing at the built entrypoint:

{
  "mcpServers": {
    "homedepot": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_homedepot/dist/index.js"],
      "env": { "HD_DEFAULT_STORE": "7074" }
    }
  }
}

HD_DEFAULT_STORE is optional (defaults to 7074, Langford BC).

Project layout

src/
  index.ts    MCP server + tool registration (stdio)
  hd.ts       curl --http2 transport for homedepot.ca
  search.ts   hd_search implementation + response mapping
  product.ts  hd_product + hd_store_availability (summary, buybox, storesvc APIs)
  stores.ts   hd_stores (store directory + postal-code geocode → nearest)

License

PolyForm Noncommercial License 1.0.0 — free to use, modify and share for noncommercial purposes. Commercial use requires a separate license from the author.