@openprints/mcp

MCP server for the OpenPrints print-on-demand API. Lets AI agents browse products, upload designs, place print orders, track shipments, and manage account balance — all through natural language.

Tools

Tool	Description
list_products	Browse available print products and variants with pricing
upload_design	Register a design image URL for reuse across orders
preview_product	Preview a product with an optional design before ordering
create_order	Place a print order — charges pre-paid balance, sends to production
get_order_status	Check status and tracking info for an order
cancel_order	Cancel an order and refund to account balance
list_orders	List recent orders with optional status filter and pagination
get_balance	Check pre-paid account balance
topup_balance	Generate a Stripe Checkout URL to add credit

Installation

Requirements: Node.js 18+

npm install -g @openprints/mcp

Or run directly without installing:

npx @openprints/mcp

Configuration

Two environment variables:

Variable	Required	Default	Description
OPENPRINTS_API_KEY	Yes	—	Your OpenPrints API key (sk_test_...)
OPENPRINTS_API_URL	No	http://localhost:3000	Base URL of the OpenPrints API

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "openprints": {
      "command": "npx",
      "args": ["-y", "@openprints/mcp"],
      "env": {
        "OPENPRINTS_API_KEY": "sk_test_your_key_here",
        "OPENPRINTS_API_URL": "https://api.openprints.io"
      }
    }
  }
}

Or if you installed globally:

{
  "mcpServers": {
    "openprints": {
      "command": "openprints-mcp",
      "env": {
        "OPENPRINTS_API_KEY": "sk_test_your_key_here",
        "OPENPRINTS_API_URL": "https://api.openprints.io"
      }
    }
  }
}

Example workflows

Place an order from scratch:

"List available products, then order a medium white t-shirt with my logo at https://example.com/logo.png, ship to Jane Smith at 10 Downing Street, London SW1A 2AA, GB."

Check on a recent order:

"What's the status of order ord_abc123? Has it shipped yet?"

Top up balance:

"Add £50 to my OpenPrints balance."

Reuse a design across multiple orders:

"Upload my design from https://cdn.example.com/design.png, then place three orders — one for each size."

Tool reference

list_products

Returns all products with variants, SKUs, and prices.

Parameter	Type	Default	Description
format	markdown | json	markdown	Response format

upload_design

Registers a design URL. Returns a design_id for reuse.

Parameter	Type	Description
url	string (URL)	Publicly accessible image URL (PNG, JPG, or PDF)

preview_product

Shows product info and variants. With a design, shows a print-ready summary.

Parameter	Type	Description
product_id	string	Product ID from list_products
design_url	string (URL)	Optional design image URL
design_id	string	Optional design ID from upload_design
format	markdown | json	Response format

create_order

Places a print order. Charges the pre-paid account balance.

Parameter	Type	Description
product_id	string	Product ID from list_products
design_id	string	Design ID from upload_design (use this or design_url)
design_url	string (URL)	Design image URL (use this or design_id)
address_name	string	Recipient full name
address_line1	string	Address line 1
address_line2	string	Address line 2 (optional)
address_city	string	City
address_postcode	string	Postcode / ZIP
address_country	string	ISO 3166-1 alpha-2 country code (e.g. GB, US)

get_order_status

Returns status, tracking number, carrier, and shipping info.

Parameter	Type	Description
order_id	string	Order ID from create_order
format	markdown | json	Response format

cancel_order

Cancels an order and refunds the amount to account balance. Irreversible.

Parameter	Type	Description
order_id	string	Order ID to cancel

list_orders

Lists orders with optional filtering and cursor pagination.

Parameter	Type	Default	Description
status	string	—	Filter by status (in_production, shipped, delivered, cancelled, …)
limit	number	20	Results per page (1–100)
starting_after	string	—	Pagination cursor — last order_id from previous page
format	markdown | json	markdown	Response format

get_balance

Returns the current pre-paid account balance in pence (GBP).

No parameters.

topup_balance

Creates a Stripe Checkout session. Returns a URL the user must open in their browser to complete payment. Does not charge the card directly.

Parameter	Type	Description
amount_cents	number	Amount to add in pence (min 100 = £1.00)
success_url	string (URL)	Redirect URL after successful payment
cancel_url	string (URL)	Redirect URL if payment is cancelled

Order statuses

Status	Meaning
payment_succeeded	Payment captured, awaiting production handoff
in_production	Sent to ShipStation, being printed
fulfillment_queued	ShipStation push failed, will be retried
shipped	Dispatched — tracking number available
delivered	Confirmed delivered
cancelled	Cancelled before production
refunded	Refunded after production
disputed	Chargeback opened
payment_failed	Payment capture failed

Development

git clone https://github.com/openprints/mcp
cd mcp
npm install
npm run build
OPENPRINTS_API_KEY=sk_test_xxx npm start

License

MIT — see LICENSE.