mcp-homedepot

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.