AI导哈

库存管理协议插件

InvenTree的MCP插件，通过标准化MCP工具暴露库存数据，使AI助手能够与库存交互。

  • by eljefedelrodeodeljefe
  • Python
  • 本地部署
  • 5 星标
  • 更新于
在 GitHub 查看 eljefedelrodeodeljefe/inventree-mcp-plugin

使用说明

invendree mcp插件

MCP（模型上下文协议）服务器插件 库存树.通过标准化的MCP工具公开InvenTree库存数据，允许像Claude这样的AI助手与您的库存进行交互。

特性

  • 零件：列出、搜索、创建和更新零件
  • 股票：列出、调整和转移库存项目
  • 位置：浏览库存位置层次结构
  • 分类：浏览零件类别层次结构
  • 订单：查看采购和销售订单
  • 物料清单：查看组件的物料清单
  • 构建：查看构建订单
  • 标签：列出和搜索零件标签

安装

pip install inventree-mcp-plugin

或者使用紫外线：

uv pip install inventree-mcp-plugin

配置

  1. 在InvenTree管理中启用插件 设置>插件设置
  2. 配置插件设置：
    • 需要认证：MCP端点是否需要身份验证（默认值： true)

MCP端点位于： /plugin/inventree-mcp/mcp/

认证

当 需要认证 如果启用（默认），则对MCP端点的每个请求都必须包含有效的凭据。插件接受与InvenTree API相同的身份验证方法：

方法 标题
API代币 Authorization: Token <your-inventree-token>
持票人 Authorization: Bearer <your-inventree-token>
基础 Authorization: Basic <base64(user:password)>
会话 基于Cookie的（浏览器会话）

若要获得API令牌，请使用InvenTree web UI(设置>API令牌)或者以编程方式请求一个：

curl -s http://your-inventree-instance/api/user/token/ \
  -H "Authorization: Basic $(echo -n admin:inventree | base64)"
# Returns: {"token": "inv-..."}

未经身份验证的请求会收到带有HTTP 401的JSON-RPC错误响应。

用户设置和权限

该插件使用经过身份验证的用户的权限通过Django ORM访问InvenTree数据。InvenTree使用基于角色的权限系统：用户属于 群组，每个组都有 规则集 那笔赠款 view, add, change，以及 delete 跨9个角色类别的权限。

重要提示： 该插件目前绕过InvenTree的 RolePermission 检查，因为它直接使用ORM而不是REST API。这意味着任何经过身份验证的用户都可以访问所有工具，而不管其角色分配如何。对于生产使用，创建一个具有适当组成员资格的专用服务帐户，以建立明确的权限边界。

推荐用户配置文件

通过InvenTree管理中心创建这些组和用户(设置>管理中心>组):

只读MCP用户 --对于只需要查询数据的AI助手：

角色 查看 添加 更改 删除
部分 是
零件类别 是
库存项目 是
库存位置 是
构建 是
采购订单 是
销售订单 是

读写MCP用户 --对于也创建/修改数据的AI助手：

角色 查看 添加 更改 删除
部分 是 是 对 是
零件类别 是
库存项目 是 是
库存位置 是
构建 是
采购订单 是
销售订单 是

创建服务帐户

  1. 首选 管理中心>组 并创建一个组（例如。 mcp-readonly 或 mcp-readwrite)
  2. 如上所示设置角色权限
  3. 首选 管理中心>用户 并创建新用户（例如。 mcp-service)
  4. 将用户分配到组
  5. 在处为用户生成API令牌 设置>API令牌

或者通过API（需要管理员帐户）：

# 1. Create a group (admin token required)
curl -X POST http://your-inventree-instance/api/user/group/ \
  -H "Authorization: Token <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "mcp-readonly"}'

# 2. Create a user assigned to that group
curl -X POST http://your-inventree-instance/api/user/ \
  -H "Authorization: Token <admin-token>" \
  -H "Content-Type: application/json" \
  -d '{"username": "mcp-service", "password": "a-strong-password", "group_ids": [<group-id>]}'

# 3. Get a token for the new user
curl -s http://your-inventree-instance/api/user/token/ \
  -H "Authorization: Basic $(echo -n mcp-service:a-strong-password | base64)"

工具权限参考

简单的工具
工具 发明树角色 最小权限
list_parts, get_part, search_parts 零件 视图
create_part 零件，零件类别 添加（零件），查看（类别）
update_part 部分 更改
list_stock_items, get_stock_item 库存项目 查看
adjust_stock 库存项目 更改
transfer_stock 库存项目、库存位置 更改（库存）、查看（位置）
list_locations, get_location, get_location_tree 库存位置 查看
list_categories, get_category, get_category_tree 零件类别 视图
list_purchase_orders, get_purchase_order 采购订单 查看
list_sales_orders, get_sales_order 销售订单 查看
list_bom_items, get_bom_for_part 零件 视图
list_build_orders, get_build_order 构建 视图
list_tags, search_tags -- 查看
组合工具
工具 发明树角色 最小权限
delete_parts 部分 删除
stock_by_category_and_location 库存项目、零件类别、库存位置 视图
stock_pivot 库存项目、零件类别、库存位置 视图

与MCP客户端一起使用

该插件使用 可流式传输的HTTP 运输。端点为：

http://your-inventree-instance/plugin/inventree-mcp/mcp/

每个请求都必须包括 Authorization 带有InvenTree API令牌的标头（请参阅 认证).

克劳德代码

添加服务器 claude mcp add 命令。使用 --scope project 将配置存储在 .mcp.json （已检查到仓库中）或对于仅本地配置省略它。

claude mcp add --transport http inventree \
  --header "Authorization: Token YOUR_INVENTREE_TOKEN" \
  http://your-inventree-instance/plugin/inventree-mcp/mcp/

为了避免以纯文本形式存储令牌，请使用环境变量：

claude mcp add --transport http inventree \
  --header "Authorization: Token ${INVENTREE_TOKEN}" \
  http://your-inventree-instance/plugin/inventree-mcp/mcp/

或者手动将配置添加到 .mcp.json （项目范围）或 ~/.claude.json （用户范围）：

{
  "mcpServers": {
    "inventree": {
      "type": "http",
      "url": "http://your-inventree-instance/plugin/inventree-mcp/mcp/",
      "headers": {
        "Authorization": "Token YOUR_INVENTREE_TOKEN"
      }
    }
  }
}

克劳德桌面版

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "inventree": {
      "type": "http",
      "url": "http://your-inventree-instance/plugin/inventree-mcp/mcp/",
      "headers": {
        "Authorization": "Token YOUR_INVENTREE_TOKEN"
      }
    }
  }
}

编辑配置文件后重新启动Claude Desktop。

双子星命令行工具

谷歌的 双子星命令行工具 支持MCP服务器。通过设置文件添加服务器 ~/.gemini/settings.json:

{
  "mcpServers": {
    "inventree": {
      "httpUrl": "http://your-inventree-instance/plugin/inventree-mcp/mcp/",
      "headers": {
        "Authorization": "Token YOUR_INVENTREE_TOKEN"
      }
    }
  }
}

ChatGPT桌面

ChatGPT桌面支持开发人员模式下的MCP（需要ChatGPT Plus、Pro、Business或Enterprise）。在下启用开发人员模式 设置>高级，然后通过添加服务器 设置>连接器.

添加自定义连接器时，请提供：

  • 网址： http://your-inventree-instance/plugin/inventree-mcp/mcp/
  • 身份验证： 令牌--值： YOUR_INVENTREE_TOKEN

用例

MCP连接到AI助手后使用的常见提示。按原样粘贴它们——你的AI将自动使用InvenTree MCP工具，而不是发出原始HTTP请求。

探索库存

  • 显示顶级零件类别以及每个类别有多少个子类别。
  • 列出“被动件”类别中的所有零件。按子类别对它们进行分组，并告诉我哪些当前处于非活动状态。
  • 在零件名称和描述中搜索与“电机驱动器”相关的任何内容。
  • 给我完整的类别树，这样我就可以了解库存是如何组织的。

库存水平

  • 哪些零件现在没有库存？列出他们的姓名、ID和类别。
  • 显示存储在“主仓库”位置及其子位置的所有库存物品。
  • 我需要将50个零件#142从“架子A”转移到“架子B”。执行并确认。
  • 调整88号零件的库存——增加200个单位以反映新的交付。

零件和物料清单

  • 获取210号零件的完整物料清单，并估算建造25个单元所需的总组件数量。
  • 305号零件依赖于哪些子组件？显示BOM树。
  • 在类别#12中创建一个名为“肖特基二极管40V 1A”的新零件，其IPN为“D-SS14”，并将其标记为可购买。
  • 找到所有标记为“过时”的零件并将其停用。在进行任何更改之前，请先显示列表。

订单和构建

  • 列出所有未完成的采购订单，并总结正在订购的内容以及来自哪些供应商。
  • 当前构建订单的状态如何？是否有过期或被阻止的？
  • 向我展示34号采购订单的行项目，并告诉我哪些零件尚未收到。
  • 过去30天内下达了哪些销售订单，订单状态如何？

清理和维护

  • 查找所有未激活且没有库存的零件。与我确认列表后删除它们。
  • 列出当前正在使用的所有标签，并告诉我哪些标签应用于少于3个部分——这些标签可能是重复的或拼写错误。
  • 显示所有标记为装配但BOM表为空的零件。

可用工具

简单--单资源CRUD

零件

工具 说明
list_parts 列出带有可选类别/活动过滤器的零件
get_part 获取详细的零件信息
search_parts 按名称或描述搜索零件
create_part 创建新零件
update_part 更新现有零件

股票

工具 说明
list_stock_items 使用可选过滤器列出库存项目
get_stock_item 获取详细的库存商品信息
adjust_stock 添加或删除库存数量
transfer_stock 将库存转移到其他位置

位置

工具 说明
list_locations 列出库存位置
get_location 获取位置详细信息
get_location_tree 获取分层位置树

分类

工具 说明
list_categories 列出零件类别
get_category 获取类别详细信息
get_category_tree 获取分层类别树

订单

工具 说明
list_purchase_orders 列出采购订单
get_purchase_order 获取包含行项目的采购订单
list_sales_orders 列出销售订单
get_sales_order 获取包含行项目的销售订单

物料清单和构建

工具 说明
list_bom_items 列出物料清单项目
get_bom_for_part 获取零件的完整BOM
list_build_orders 列出构建订单
get_build_order 获取构建订单详细信息

标签

工具 说明
list_tags 列出所有标签
search_tags 按名称搜索标签

组合式——多资源运营

工具 说明
delete_parts 按ID删除多个零件（带安全检查）
stock_by_category_and_location 按类别和位置划分的库存数量枢轴
stock_pivot 具有完整类别/位置层次结构路径的库存数量枢轴

发展

先决条件

  • 紫外线 --Python包管理器
  • 学前班 --预提交钩子运行器（替换 pre-commit)

安装prek并设置git挂钩：

prek install

# Clone the repository
git clone https://github.com/eljefedelrodeodeljefe/inventree-mcp-plugin.git
cd inventree-mcp-plugin

# Install dependencies
uv sync --dev

# Run linting
uv run ruff check .
uv run ruff format --check .

# Run unit tests (mocked, no InvenTree required)
uv run pytest -v

集成测试

A. docker-compose.dev.yml 包括旋转a 一次性 InvenTree实例已挂载PostgreSQL、Redis和插件卷。所有状态都存在于Docker卷中，这些卷在拆卸时会被销毁。

集成先决条件

  • Docker和Docker Compose v2+

快速开始

# Start InvenTree and seed the demo dataset
./scripts/integration-test.sh up

# MCP endpoint is now live at:
#   http://localhost:8000/plugin/inventree-mcp/mcp/

# Get an admin API token (useful for curl/httpie testing)
./scripts/integration-test.sh token

测试账户

这 up 命令种子InvenTree的 演示数据集 并创建专用MCP服务帐户：

用户名 密码 用途
admin inventree 超级用户——完全访问权限，用于管理任务
mcp-service mcp-service MCP服务帐户--通过管理中心分配角色
mcp-readonly mcp-readonly 无角色--用于验证权限拒绝
allaccess nolimits 演示用户--完全权限
reader readonly 演示用户--仅供查看

之后 up，配置 mcp-readwrite 通过管理中心访问组的角色权限(管理中心>组>mcp读写>规则集).看 用户设置和权限 对于推荐的角色矩阵。

为不同用户获取令牌：

./scripts/integration-test.sh token           # mcp-service (default)
./scripts/integration-test.sh token admin     # admin superuser
./scripts/integration-test.sh token readonly  # mcp-readonly (no roles)

重置状态

# Wipe all data and re-seed (keeps containers running)
./scripts/integration-test.sh reset

这运行 invoke dev.delete-data 紧随其后 invoke dev.setup-test -i，无需重新构建容器，即可为您带来全新的体验。

拆除

# Stop containers and delete all volumes
./scripts/integration-test.sh down

冒烟测试

该脚本包括一个经过身份验证的烟雾测试套件，用于端到端验证MCP端点：

./scripts/integration-test.sh smoke

这会自动获得一个令牌并进行测试：

  1. 未经身份验证的请求被拒绝（401）
  2. 已验证 initialize 成功
  3. 已验证 tools/list 返回已注册的工具
  4. 已验证 tools/call 为了 list_parts 成功

手动MCP测试

在堆栈运行时，首先获取一个令牌，然后测试端点：

# Get a token
TOKEN=$(./scripts/integration-test.sh token)

# Initialize the MCP session
curl -X POST http://localhost:8000/plugin/inventree-mcp/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Token ${TOKEN}" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": { "name": "test", "version": "0.1.0" }
    }
  }'

# List available tools
curl -X POST http://localhost:8000/plugin/inventree-mcp/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Token ${TOKEN}" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

# Call a tool
curl -X POST http://localhost:8000/plugin/inventree-mcp/mcp/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "Authorization: Token ${TOKEN}" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": { "name": "list_parts", "arguments": { "limit": 5 } }
  }'

脚本引用

./scripts/integration-test.sh up               # Start stack, seed data, create MCP users
./scripts/integration-test.sh reset            # Wipe data, re-seed, re-create MCP users
./scripts/integration-test.sh token            # Print mcp-service API token
./scripts/integration-test.sh token admin      # Print admin API token
./scripts/integration-test.sh token readonly   # Print mcp-readonly API token
./scripts/integration-test.sh smoke            # Run authenticated smoke tests
./scripts/integration-test.sh status           # Check if InvenTree is healthy
./scripts/integration-test.sh down             # Tear down + delete volumes

释放

发布是自动化的 python语义发布。它解析自上次标记以来的常规提交消息，确定下一个版本更新(patch, minor，或 major)，更新中的版本 pyproject.toml，生成 CHANGELOG.md，创建一个git标签，并发布GitHub版本。

工作流程需要手动触发，以避免在每次合并时创建版本 main.

从GitHub用户界面

  1. 首选 行动→ 发布
  2. 点击 运行工作流
  3. 选择 main 分支并确认

从命令行

gh workflow run release.yml --ref main

要观看跑步直到完成：

gh workflow run release.yml --ref main && gh run watch --exit-status

当地干跑

在不做任何更改的情况下预览下一个版本：

uv run semantic-release version --print

许可证

麻省理工学院

相关 MCP