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令牌，请使用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 " \
  -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 " \
  -H "Content-Type: application/json" \
  -d '{"username": "mcp-service", "password": "a-strong-password", "group_ids": []}'

# 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)"

工具权限参考

简单的工具

组合工具

与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

零件

股票

位置

分类

订单

物料清单和构建

标签

组合式——多资源运营

发展

先决条件

• 紫外线 --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服务帐户：

之后 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

许可证

麻省理工学院