Heartland MCP

Heartland零售MCP服务器

一个MCP（模型上下文协议）服务器，将Claude连接到 Heartland零售 API问克劳德关于你的销售、库存和供应商的自然语言问题——克劳德会调用正确的工具并总结结果。

______________________________________________________________________

设置

先决条件

• Node.js 18+
• 心脏地带零售API代币(如何获得一个)
• 克劳德代码CLI(npm install -g @anthropic-ai/claude-code)

步骤1-获取Heartland API代币

1. 登录您的Heartland Retail仪表板
2. 点击右上角的你的名字→ 我的账户
3. 点击 API 打开API令牌页面
4. 点击 生成新令牌，输入描述，然后单击 生成令牌
5. 立即复制令牌，它不会再次显示

详细信息：https://dev.retail.heartland.us/#authentication

步骤2——安装和构建

git clone https://github.com/bamherndon/HeartlandMCP.git
cd HeartlandMCP
npm install
npm run build

步骤3--使用Claude Code注册

运行此命令一次以注册服务器。替换 your_token 和 yourstore 根据您的实际值：

claude mcp add heartland-retail \
  --transport stdio \
  --scope user \
  -e HEARTLAND_API_TOKEN=your_token \
  -e HEARTLAND_BASE_URL=https://yourstore.retail.heartland.us \
  -- node /path/to/HeartlandMCP/dist/index.js

注： --scope user 为您的所有Claude Code会话注册服务器。使用 --scope local 将其仅限于当前项目。

步骤4——验证连接

启动一个新的Claude Code会话并运行：

/mcp

你应该看看 heartland-retail 以绿色连接状态列出。现在，您可以向Claude询问有关Heartland数据的问题。

______________________________________________________________________

可用工具

get_vendors

按名称搜索供应商。在运行库存或销售报告之前，使用此功能查找供应商的数字ID。

示例提示：

• “寻找名为Levi的供应商”
• “列出所有供应商”

______________________________________________________________________

get_vendor_item_counts

返回特定供应商的期末库存数量，按位置、供应商、物料ID和物料描述分组。

示例提示：

• “我们从供应商100026那里有多少台？”
• “显示截至1月31日供应商100026的商品计数”

______________________________________________________________________

get_vendor_sales

返回特定供应商在日期范围内销售的商品，按位置、供应商、商品ID和描述分组。

退货： 售出数量、总成本、未结订单数量、现有数量、最后售出日期——每个地点的每件商品。

示例提示：

• “供应商100026上个月卖了什么？”
• “显示哥伦比亚运动服2026年第一季度的销售额”

______________________________________________________________________

get_item_history

返回单个项目的完整库存历史记录，包括所有数量变化（交易）和地点之间的转移。

示例提示：

• “显示SKU ABC123的库存历史记录”
• “1月份的987654号物品怎么了？”

______________________________________________________________________

get_item_sales_velocity

计算每月销售的单位，按项目细分。返回每个项目的平均值和每月总计。

退货： 平均数量/月、平均净销售额/月、月度明细——每个项目和整体。

示例提示：

• “供应商100026在过去一年的销售速度如何？”
• “SKU ABC123的销售速度有多快？”

______________________________________________________________________

get_sales_grouped_by_vendor

返回给定日期范围内按地点和供应商分组的净销售额、净销售量和总成本。

示例提示：

• “按供应商显示2026年3月的销售额”
• “给我一份2026年第一季度的供应商销售摘要”

______________________________________________________________________

get_sales_grouped_by_department

返回按地点和部门分组的日期范围内的总成本和净销售量。不包括Minifig Maker子部门。

示例提示：

• “按部门显示过去6个月的销售额”
• “今年哪个部门售出的单位最多？”

______________________________________________________________________

get_inventory_by_vendor

返回截至给定日期按地点和供应商分组的期末库存数量、成本和零售价。

示例提示：

• “按供应商显示截至今天的库存水平”
• “2月28日，每个供应商都有什么库存？”

______________________________________________________________________

get_inventory_by_department

返回截至给定日期按地点和部门分组的期末库存数量和成本。不包括Minifig Maker子部门。

示例提示：

• “显示截至今天按部门列出的期末库存”
• “按部门划分的库存成本是多少？”

______________________________________________________________________

list_locations

列出Heartland Retail的所有店铺位置。在创建库存调整之前，使用此功能查找位置的ID。

示例提示：

• “列出所有位置”
• “市中心商店的位置ID是什么？”

______________________________________________________________________

get_item

按内部ID或SKU查找特定库存商品。返回完整的商品详细信息，包括描述、定价、供应商和库存字段。

示例提示：

• “查找项目12345”
• “显示SKU ABC123的详细信息”

______________________________________________________________________

update_item

通过HTTP PUT更新库存项目。支持部分更新——只发送您提供的字段，因此省略的字段保持不变。

示例提示：

• “将项目12345的价格设置为19.99”
• “将SKU 60170标记为红色标签”
• “更新项目104273的描述和成本”

______________________________________________________________________

create_inventory_adjustment

创建库存调整集并向其中添加物料行。用于记录特定位置的数量更正。

退货： 创建的调整集ID、完整的调整集响应和每个添加行的结果。

示例提示：

• 在位置5创建一个库存调整，原因为3，添加10个单位的12345，成本为9.99
• “由于收缩（原因2），将位置1处的99887项下调2个单位，单位成本5.00”

______________________________________________________________________

run_report

对指标、分组和日期范围的任意组合运行灵活的报告分析器查询。

示例提示：

• “显示上个月按地点划分的净销售额”
• “运行一份按供应商分组的第一季度毛利率和成本报告”
• “按部门显示期末库存数量和零售价值”

______________________________________________________________________

list_metrics

返回要在中使用的可用度量名称的完整目录 run_report.

类别：

• source_sales.* --净销售额、总销售额、折扣、退货、税款、交易、已售商品、平均销售额、成本、毛利、毛利率
• location_sales.* --与上述相同，加上销售和库存周转
• beginning_inventory.* / ending_inventory.* --数量、成本、零售、物品、SKU、款式、部门、类别、供应商、季节、地点、重新订购/补货/积压标志、平均值
• shipping.* --发货、收货、成本
• payment.* --数量，计数

示例提示：

• “有哪些可用的指标？”
• “列出我可以报告的所有库存指标”

______________________________________________________________________

list_groups

返回要在中使用的所有可用分组维度 run_report.

类别：

• item.* --描述、SKU、UPC、部门、类别、子类、供应商、季节、风格、自定义字段
• customer.* --姓名、电子邮件、城市、州、邮政编码、客户类型
• location.* --名称、代码
• date.* --日期、星期、月份、季度、年份、星期几
• time.* --小时
• payment.* --付款类型，投标

示例提示：

• “我可以根据什么对报告进行分组？”
• “显示所有可用的日期分组”

______________________________________________________________________

示例工作流程

按地点划分的月度销售汇总：

“显示2026年2月按地点划分的净销售额、交易额和毛利率”

供应商库存查询：

“找到‘Columbia Sportswear’的供应商ID，然后告诉我截至今天我们从他们那里有多少台”

部门销售渠道：

“按部门显示过去6个月的销售额，然后按部门显示期末库存——哪些部门库存量很大？”

每日销售趋势：

“过去30天我们的净销售额是多少？”

供应商销售渠道：

“找到哥伦比亚运动服的供应商ID，然后向我展示他们上个季度销售了什么，以及我们手头还有多少台”

项目速度和重新订购计划：

“供应商100026在过去一年的销售速度如何？哪些商品销售最快？”

项目审核：

“显示SKU ABC123的完整库存历史记录——所有交易和转账”

______________________________________________________________________

发展

npm run build    # compile TypeScript
npm run dev      # watch mode

API文件：https://dev.retail.heartland.us/