Tryton Stock MCP

Tryton Stock MCP is a read-only Model Context Protocol server for investigating product, lot, location and stock-movement history in Tryton 6.x.

It turns questions such as “audit the complete history of product X” into a structured investigation covering movement states, lots, incoming shipments, outgoing shipments, internal transfers, locations, official contextual quantities and derived diagnostic balances.

Safety model

• The MCP tools expose no create, write, delete or workflow RPC methods.

• Credentials are read only from environment variables.

• Tool logs contain metadata only: tool name, status, duration and error type.

• Record searches are restricted to product and stock-related models.

• describe_model may inspect metadata for any model, but it does not read records.

• Derived balances are investigative evidence, not official Tryton stock.

Use a dedicated Tryton account with read-only, least-privilege access. This project does not make a write-capable account safe. Avoid sending clinical or personal data to an MCP client unless its privacy properties are acceptable for your environment.

Related MCP server: Inventory Analysis MCP Server

Requirements

• Python 3.10 or newer

• Tryton 6.x with JSON-RPC enabled

• Read access to product and stock models

Recommended installation with pipx

pipx installs the MCP in its own isolated Python environment and exposes the tryton-stock-mcp command globally.

If pipx is not installed yet:

python -m pip install --user pipx
python -m pipx ensurepath

Open a new terminal after ensurepath so the installed commands are available.

Install directly from GitHub:

pipx install "git+https://github.com/SamuelBalbas/tryton-stock-mcp.git"

Or install from a local clone while developing:

git clone <your-fork-or-repository-url> tryton-stock-mcp
cd tryton-stock-mcp
pipx install .

Run the server:

tryton-stock-mcp

Upgrade or uninstall it:

pipx upgrade tryton-stock-mcp
pipx uninstall tryton-stock-mcp

When a PyPI release becomes available, installation can be shortened to pipx install tryton-stock-mcp.

Development installation

The repository-local workflow remains available for contributors and troubleshooting:

git clone <your-fork-or-repository-url> tryton-stock-mcp
cd tryton-stock-mcp
python -m venv .venv

Windows PowerShell:

.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"

Linux or macOS:

source .venv/bin/activate
python -m pip install -e ".[dev]"

Configure

The server reads its configuration from the process environment. .env.example is a reference file; it is not loaded automatically.

Required variables:

Optional variables:

Remote HTTP is rejected unless explicitly enabled. HTTPS is strongly recommended whenever Tryton is not running on the same machine.

Run from a development checkout

python -m tryton_stock_mcp

The server uses MCP stdio, so normal output must not be written to stdout.

MCP client configuration

With the recommended pipx installation, the client only needs the installed command and the Tryton environment variables:

{
  "mcpServers": {
    "tryton-stock": {
      "command": "tryton-stock-mcp",
      "args": [],
      "env": {
        "TRYTON_HOST": "localhost",
        "TRYTON_PORT": "8000",
        "TRYTON_DATABASE": "your_database",
        "TRYTON_USER": "readonly_auditor",
        "TRYTON_PASSWORD": "replace_me",
        "TRYTON_PROTOCOL": "http"
      }
    }
  }
}

If the MCP client does not inherit the shell PATH, use the absolute path reported by pipx environment or pipx list. For a development checkout, use the virtual environment's absolute Python path with the arguments -m tryton_stock_mcp.

Guided audit

The main tool is audit_product_history.

Inputs:

• product_query: product name or code, or

• product_id: exact Tryton product variant ID

• lot_number: optional lot filter

• include_cancelled: include cancelled movements, default true

Exactly one of product_query or product_id is required. When a query matches multiple products, the tool returns needs_product_selection with candidates; the caller must choose one before the full audit runs. Lots follow the same rule.

The successful result includes:

• every matching movement, retrieved in bounded pages until exhaustion;

• counts for done, draft, staging, assigned, cancelled and other states;

• incoming, outgoing, internal and other workflow counts;

• shipments and origins exposed by stock.move;

• registered, missing and cross-product lot evidence;

• pending movements and effective-date inconsistencies;

• official product quantities for internal locations;

• chronological derived balances and first-negative evidence;

• a concise Markdown report plus complete JSON evidence.

Additional tools

The server also exposes focused tools for searching products, lots, locations and moves; finding pending moves; reconstructing ledgers; comparing products; querying official quantities; and generating generic product or move reports.

search_reference_globally is intentionally restricted to the approved stock models. describe_model is the only tool that accepts any Tryton model name, and it returns field metadata only.

Diagnostic limits

Tryton's official stock calculation depends on context, company, locations and date. The MCP reports official contextual quantity separately from balances it reconstructs by adding completed incoming movements and subtracting completed outgoing movements. Never use a reconstructed balance as an automatic inventory adjustment.

Development

python -m pip install -e ".[dev]"
python -m pytest

Tests use synthetic JSON-RPC responses and do not require a live database.

License

Apache License 2.0. See LICENSE.