inventree-mcp-plugin

MCP (Model Context Protocol) server plugin for InvenTree. Exposes InvenTree inventory data through standardized MCP tools, allowing AI assistants like Claude to interact with your inventory.

Features

Parts: List, search, create, and update parts
Stock: List, adjust, and transfer stock items
Locations: Browse stock location hierarchy
Categories: Browse part category hierarchy
Orders: View purchase and sales orders
BOM: View bill of materials for assemblies
Builds: View build orders
Tags: List and search part tags

Installation

pip install inventree-mcp-plugin

Or with uv:

uv pip install inventree-mcp-plugin

Configuration

Enable the plugin in InvenTree Admin under Settings > Plugin Settings
Configure plugin settings:
- Require Authentication: Whether the MCP endpoint requires authentication (default: true)

The MCP endpoint is available at: /plugin/inventree-mcp/mcp/

Authentication

When Require Authentication is enabled (the default), every request to the MCP endpoint must include a valid credential. The plugin accepts the same auth methods as the InvenTree API:

| Method | Header | |--------|--------| | API Token | Authorization: Token <your-inventree-token> | | Bearer | Authorization: Bearer <your-inventree-token> | | Basic | Authorization: Basic <base64(user:password)> | | Session | Cookie-based (browser sessions) |

To obtain an API token, either use the InvenTree web UI (Settings > API Tokens) or request one programmatically:

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

Unauthenticated requests receive a JSON-RPC error response with HTTP 401.

User Setup and Permissions

The plugin accesses InvenTree data through the Django ORM using the permissions of the authenticated user. InvenTree uses a role-based permission system: users belong to groups, and each group has rule sets that grant view, add, change, and delete permissions across 9 role categories.

Important: The plugin currently bypasses InvenTree's RolePermission checks because it uses the ORM directly rather than the REST API. This means any authenticated user can access all tools regardless of their role assignments. For production use, create a dedicated service account with appropriate group membership to establish a clear permission boundary.

Recommended user profiles

Create these groups and users via the InvenTree Admin Center (Settings > Admin Center > Groups):

Read-only MCP user — for AI assistants that only need to query data:

| Role | view | add | change | delete | |------|------|-----|--------|--------| | Part | yes | | | | | Part Category | yes | | | | | Stock Item | yes | | | | | Stock Location | yes | | | | | Build | yes | | | | | Purchase Order | yes | | | | | Sales Order | yes | | | |

Read-write MCP user — for AI assistants that also create/modify data:

| Role | view | add | change | delete | |------|------|-----|--------|--------| | Part | yes | yes | yes | | | Part Category | yes | | | | | Stock Item | yes | | yes | | | Stock Location | yes | | | | | Build | yes | | | | | Purchase Order | yes | | | | | Sales Order | yes | | | |

Creating the service account

Go to Admin Center > Groups and create a group (e.g. mcp-readonly or mcp-readwrite)
Set the role permissions as shown above
Go to Admin Center > Users and create a new user (e.g. mcp-service)
Assign the user to the group
Generate an API token for the user at Settings > API Tokens

Or via the API (requires an admin account):

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

Tool permission reference

Simple tools

| Tool | InvenTree Role(s) | Minimum Permission | |------|-------------------|--------------------| | list_parts, get_part, search_parts | Part | view | | create_part | Part, Part Category | add (part), view (category) | | update_part | Part | change | | list_stock_items, get_stock_item | Stock Item | view | | adjust_stock | Stock Item | change | | transfer_stock | Stock Item, Stock Location | change (stock), view (location) | | list_locations, get_location, get_location_tree | Stock Location | view | | list_categories, get_category, get_category_tree | Part Category | view | | list_purchase_orders, get_purchase_order | Purchase Order | view | | list_sales_orders, get_sales_order | Sales Order | view | | list_bom_items, get_bom_for_part | Part | view | | list_build_orders, get_build_order | Build | view | | list_tags, search_tags | — | view |

Combinatory tools

| Tool | InvenTree Role(s) | Minimum Permission | |------|-------------------|--------------------| | delete_parts | Part | delete | | stock_by_category_and_location | Stock Item, Part Category, Stock Location | view | | stock_pivot | Stock Item, Part Category, Stock Location | view |

Usage with MCP Clients

The plugin uses the Streamable HTTP transport. The endpoint is:

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

Every request must include an Authorization header with an InvenTree API token (see Authentication).

Claude Code

Add the server with the claude mcp add command. Use --scope project to store the config in .mcp.json (checked into the repo) or omit it for local-only config.

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

To avoid storing the token in plain text, use an environment variable:

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

Or add the config manually to .mcp.json (project scope) or ~/.claude.json (user scope):

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

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %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"
      }
    }
  }
}

Restart Claude Desktop after editing the config file.

Gemini CLI

Google's Gemini CLI supports MCP servers. Add the server via the settings file at ~/.gemini/settings.json:

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

ChatGPT Desktop

ChatGPT Desktop supports MCP in Developer Mode (requires ChatGPT Plus, Pro, Business, or Enterprise). Enable Developer Mode under Settings > Advanced, then add the server via Settings > Connectors.

When adding a custom connector, provide:

URL: http://your-inventree-instance/plugin/inventree-mcp/mcp/
Authentication: Token — value: YOUR_INVENTREE_TOKEN

Use Cases

Common prompts to use once the MCP is connected to your AI assistant. Paste them as-is — your AI will use the InvenTree MCP tools automatically rather than making raw HTTP requests.

Exploring inventory

Show me the top-level part categories and how many subcategories each one has.
List all parts in the "Passives" category. Group them by subcategory and tell me which ones are currently inactive.
Search for anything related to "motor driver" across part names and descriptions.
Give me the full category tree so I can understand how the inventory is organised.

Stock levels

Which parts have zero stock right now? List their names, IDs and categories.
Show me all stock items stored in the "Main Warehouse" location and its sub-locations.
I need to transfer 50 units of part #142 from "Shelf A" to "Shelf B". Do it and confirm.
Adjust stock for part #88 — add 200 units to reflect a new delivery.

Parts and BOMs

Get the full bill of materials for part #210 and estimate the total component count needed to build 25 units.
What sub-assemblies does part #305 depend on? Show the BOM tree.
Create a new part called "Schottky Diode 40V 1A" in category #12 with IPN "D-SS14" and mark it as purchaseable.
Find all parts tagged "obsolete" and deactivate them. Show me the list before making any changes.

Orders and builds

List all open purchase orders and summarise what's being ordered and from which suppliers.
What's the status of current build orders? Are any overdue or blocked?
Show me the line items for purchase order #34 and tell me which parts haven't been received yet.
Which sales orders have been placed in the last 30 days and what's their status?

Inventree MCP Plugin

Install / Use

README