Skip to main content
Glama
metrc-mcp
by AM253906

metrc-mcp

An MCP (Model Context Protocol) server for the METRC cannabis track-and-trace API, focused on the workflows a processor/manufacturer actually runs day to day: checking active package inventory, resolving tags, reconciling transfer manifests, and pulling lab test results.

I built this after several years running licensed processing operations, where "check METRC" is a dozen-times-a-day interruption. Wrapping the API as MCP tools lets an assistant answer questions like "which of our active packages are still awaiting lab results?" or "reconcile yesterday's incoming manifest against what we received" directly against the compliance system of record.

Scope

This deliberately does not wrap the full METRC API. METRC exposes a couple hundred endpoints across cultivation, retail, and processing; most integrations touch a small fraction. This server covers the processor slice:

Tool

What it does

list_facilities

Facilities visible to your user key, with license numbers

list_active_packages

Active inventory with testing state and hold status

get_package

Full record for one package by tag label

finish_package

Mark a zero-quantity package finished (write, gated)

list_items

The item catalog packages are created against

list_incoming_transfers / list_outgoing_transfers

Manifests in and out

get_lab_test_results

Test results for a package by numeric ID

Cultivation (plants, harvests) and retail (sales receipts) endpoints are out of scope. Adding a domain means one new file in src/tools/.

Related MCP server: @smart-compost/mcp

Safety model

METRC is a legal record. Mistakes in it are compliance findings, not bugs.

  • Read-only by default. Write tools throw unless METRC_ALLOW_WRITES=true is set explicitly.

  • Sandbox support. Set METRC_SANDBOX=true to target your state's sandbox instance. Do not enable writes against a production license until the workflow has been tested there.

  • Bounded output. List tools cap at 100 rows and say so, rather than flooding the model's context with a busy facility's full inventory.

METRC auth, briefly

METRC deploys per state (api-ok.metrc.com, api-ca.metrc.com, ...) and authenticates with HTTP Basic where the username is the software vendor's API key and the password is the user's API key. The vendor key identifies the integrator; the user key determines which facilities you can see. Both are required. This trips up most first-time integrators, who expect a single bearer token.

Endpoint paths and payload fields can differ slightly between states and API versions. This server targets the v2 endpoints; if your state lags on a particular resource, the 404 error message will say which path failed.

Setup

npm install
npm run build

Configure via environment (see .env.example):

METRC_STATE=ok                  # two-letter state code
METRC_VENDOR_API_KEY=...        # from your METRC vendor account
METRC_USER_API_KEY=...          # from your METRC user profile
METRC_LICENSE_NUMBER=...        # optional default license
METRC_SANDBOX=true              # strongly recommended to start
METRC_ALLOW_WRITES=false        # keep false until tested

Register with an MCP client (Claude Desktop shown):

{
  "mcpServers": {
    "metrc": {
      "command": "node",
      "args": ["/path/to/metrc-mcp/dist/index.js"],
      "env": {
        "METRC_STATE": "ok",
        "METRC_VENDOR_API_KEY": "...",
        "METRC_USER_API_KEY": "...",
        "METRC_SANDBOX": "true"
      }
    }
  }
}

Testing

npm test

METRC vendor sandbox access requires completing METRC's training and API User Agreement process, so this client is validated against a mocked METRC instance instead (test/mock-metrc.ts), with payloads shaped like the real v2 responses. The suite covers two layers:

  • Client tests — Basic auth construction (vendor key as username, user key as password), query serialization, 429 retry with backoff and eventual surfacing, normalization of METRC's inconsistent error shapes, and license resolution.

  • End-to-end stdio tests — the compiled server is spawned as a real MCP process and driven over JSON-RPC, the same path Claude Desktop uses. These verify tool registration, response summarization, readable tool-level errors, and that write tools are refused in read-only mode before any network call is attempted.

METRC_BASE_URL exists solely as the test hook that points the client at the mock.

Development

npm run dev        # run from source via tsx
npm run build      # compile to dist/

The layering is: src/metrc/client.ts owns HTTP, auth, timeouts, and 429 retry; src/tools/* define MCP tools per domain and summarize responses; src/config.ts validates environment once at startup. Tool handlers never touch fetch directly.

License

MIT

Available Tools

8 tools
finish_packageFinish package (write)A

Mark a zero-quantity package as finished, removing it from active inventory. This modifies the state compliance record. Requires METRC_ALLOW_WRITES=true.

Inputs: label (required), actualDate (required), licenseNumber.

get_lab_test_resultsGet lab test resultsA

Fetch lab test results for a package by its numeric package ID (not the tag label — use get_package first to resolve the ID). Returns test type, pass/fail, measured level, and testing lab.

Inputs: packageId (required), licenseNumber.

get_packageGet package by labelA

Look up a single package by its METRC tag label (e.g. 1A4FF0100000022000000123) and return its full record, including source and testing details.

Inputs: label (required), licenseNumber.

list_active_packagesList active packagesA

List active (unfinished) packages at a facility: label, item, quantity, lab testing state, and hold status. This is the day-to-day inventory view for a processor.

Inputs: licenseNumber, lastModifiedEnd, lastModifiedStart.

list_facilitiesList facilitiesA

List the facilities the configured METRC user key can access, with license numbers and license types. Call this first if you don't know which license number to use for other tools.

Inputs: no named parameters.

list_incoming_transfersList incoming transfersA

List incoming transfers for a facility: manifest number, shipper, and package count. Useful for reconciling deliveries against manifests.

Inputs: licenseNumber.

list_itemsList itemsA

List the facility's item catalog (the product definitions packages are created against): name, category, and unit of measure.

Inputs: licenseNumber.

list_outgoing_transfersList outgoing transfersA

List outgoing transfers for a facility: manifest number, recipient, and package count.

Inputs: licenseNumber.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4/5.0

    Scored across 8 tools

    Disambiguation5/5

    Each tool targets a distinct resource and action: facilities, active packages, single package lookup, finishing packages, items, incoming/outgoing transfers, and lab results. Even the package-related tools are clearly separated by scope (list vs. get vs. lab results).

    Naming Consistency5/5

    Tool names consistently follow a verb_noun pattern using snake_case, with list_ for collection queries, get_ for single-record lookups, and finish_ for the one mutation. This makes the toolset predictable and easy for an agent to route.

    Tool Count5/5

    Eight tools is a well-scoped size for this domain. Each tool covers a meaningful part of the METRC workflow without unnecessary redundancy or bloat.

    Completeness3/5

    The read-side coverage is solid for facilities, packages, items, transfers, and lab results, and finish_package provides one mutation. However, common lifecycle operations such as creating or adjusting packages, receiving incoming transfers, and creating outgoing transfers are missing, leaving agents able to observe but not fully complete many compliance workflows.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      MCP server for running infrastructure health checks with TIBET provenance. It enables users to define, execute, and audit process health checks with dependency chaining and drift tracking.
      6
      MIT
    • F
      license
      C
      quality
      C
      maintenance
      A production-ready MCP server for inventory and interaction with Alterios/LIMS instances, enabling project listing, readonly data queries via REST and script-services, and controlled write operations.
      100
      -
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides a sovereign, MIT-licensed MCP server for professional-service workflows, running entirely on your infrastructure with Ed25519 cryptographic signing for every action.
      MIT