Content
# M5Stack MCP Server
MCP (Model Context Protocol) server to support selection of M5Stack products.
## Features
- **Offline high-speed operation** — Includes a normalized product snapshot (integrated from shop.m5stack.com and official docs)
- **Compatibility judgment** — 3-layer engine with form factor rules and manual curation rules. Judgments always include basis and confidence.
- **Configuration proposal** — Returns structured data for role-based candidate products, compatibility matrix, and minimum bundle, with final judgment left to LLM.
- **Live price and stock** — Retrieves current prices from shop.m5stack.com as needed (with caching)
## Setup
```bash
npm install
npm run build
```
### Register with Claude Code
```bash
claude mcp add m5stack -- node /path/to/M5Stack-MCP/dist/index.js
```
### Register with Claude Desktop
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"m5stack": {
"command": "node",
"args": ["/path/to/M5Stack-MCP/dist/index.js"]
}
}
}
```
## Tool List
| Tool | Purpose |
|--------|------|
| `search_products` | Product search by keyword, category, tag, and price |
| `get_product` | Product details (specs, Grove port, docs link) by handle/SKU |
| `list_categories` | Category tree and product count |
| `check_compatibility` | Compatibility judgment for controller and peripheral devices (with basis and confidence) |
| `suggest_configuration` | Configuration proposal from purpose description |
| `get_price_stock` | Live price and stock retrieval (up to 10 items) |
| `update_catalog` | Update product catalog on the fly (for new products) |
## Usage Examples (Claude Queries)
- "What is the minimum configuration to measure temperature and humidity and send it to a server via Wi-Fi?"
- "Can I use ENV IV Unit with AtomS3 Lite?"
- "Which one should I choose between CoreS3 and Core2? Is there stock available?"
- "I want to build a soil moisture monitoring prototype with a budget of $50"
Actual response example:
## Data Update
M5Stack frequently releases new products, so we track them through multiple channels. **Basically, no action is required, and the installed environment will automatically follow the latest updates.**
1. **Automatic update on startup (local)** — If the snapshot is older than 7 days, it will be re-acquired from official sources and saved to `~/.cache/m5stack-mcp/`.
2. **`update_catalog` tool** — Claude can re-acquire data on the fly (in about 15-30 seconds)
3. **Weekly automatic update (GitHub Actions)** — Data is re-acquired every Monday, and if there are changes, it will be automatically committed.
4. **Manual**: `npm run update-data` (re-generate `data/`)
Tool responses always include `data_as_of` (snapshot acquisition date and time). If the data is older than 45 days, a warning to update the catalog will be included.
## Data Structure
| File | Content | Management |
|---------|------|------|
| `data/products.json` | Normalized product snapshot | Automatically generated |
| `data/categories.json` | Category tree and product count | Automatically generated |
| `data/meta.json` | Acquisition date and time, product count | Automatically generated |
| `data/compatibility-rules.json` | Manual curation of controller generation and Grove port | Manual management |
## Development
```bash
npm run dev # Start with tsx
npm test # vitest
npm run inspect # MCP Inspector for manual tool testing
```
## License
MIT ([LICENSE](LICENSE))
The included product snapshot (e.g., `data/products.json`) is generated from the following official sources:
- [shop.m5stack.com](https://shop.m5stack.com) — Copyright of product names, descriptions, and image URLs belongs to M5Stack Technology Co., Ltd.
- [m5stack/m5-docs](https://github.com/m5stack/m5-docs) (MIT License)
This project is an unofficial tool and is not affiliated with M5Stack.
