TPT MCP

A local Model Context Protocol server for preparing and uploading Teachers Pay Teachers listings through an authenticated Chrome browser. Unofficial; not affiliated with or endorsed by TPT.

Built with the official MCP SDK and Playwright. It uses TPT's seller web interface, not an undocumented upload API. A real private draft was uploaded, saved and reopened to verify its files, metadata and rich-text description during development. Public publication and every possible product type have not been independently validated.

Features

• Validate local product packages and complete listing metadata.

• Upload ZIPs, PDF previews, optional videos and four custom images.

• Enter real paragraphs, bold headings and bullet lists.

• Fill pricing, tax code, grades, subjects, tags, formats and teaching details.

• Use Upload thumbnails now for custom uploads and Auto generate thumbnails from the product file otherwise. Never submit with Upload thumbnails later selected.

• Save private drafts or submit active listings with explicit authorization.

• Record attempts before submission to prevent blind duplicate retries.

• Reopen saved listings and verify metadata and asset references.

Install

Requires Node.js 22+ and an installed Google Chrome browser.

git clone https://github.com/grahamwaters/tpt-mcp.git
cd tpt-mcp
npm ci

For Codex, register using absolute paths:

codex mcp add educode-tpt --env TPT_WORKSPACE=/absolute/path/to/product-workspace -- node /absolute/path/to/tpt-mcp/server.mjs

For another MCP client, configure a stdio server with node, the absolute server.mjs path, and TPT_WORKSPACE in its environment. Reload the client to discover tools. No HTTP server or API key is required.

Product workspace

Provide your own assets. This repository includes only schema examples and synthetic test fixtures, not commercial products or seller data.

product-workspace/
  release/upload-ready/
    UPLOAD-MANIFEST.json
    example-product/
      product.json
      listing.json
      example-product.zip
      preview.pdf
      cover.png
      thumb-1.png
      thumb-2.png
      thumb-3.png

Start with the manifest example and the listing example. A minimal product.json contains the matching id and title. File paths resolve within TPT_WORKSPACE; path traversal and symlink escapes are rejected. The complete listing schema is in listing.mjs.

Replace all sample claims and choices with accurate values. Set review.releaseReady only after reviewing the actual product and its rights. The example remains blocked from active publication until replaced. Tax code selection must reflect the actual product; the sample is not tax advice.

Use

1. Call tpt_open_login and sign in directly in the dedicated Chrome window. Login persists locally in .local/browser. Never share that directory.

2. Call tpt_list_products and tpt_get_product to review a package.

3. Call tpt_prepare_product with its local id. It validates listing.json, fills the form and selects the assets.

4. Call tpt_inspect. Wait for processed-upload receipts and review the actual listing. Use tpt_category_options and tpt_choose_category to inspect or change current choices.

5. Call tpt_submit_product with id, authorized: true and active: false for a private draft. Use active: true only with authorization to publish. A caller-supplied flag is not an independent authentication or approval system.

6. Read the saved seller listing's numeric product ID, then call tpt_verify_saved_product with id and remoteId.

tpt_format_saved_description repairs formatting in an existing matching listing; submit separately to save. tpt_product_status reads the journal. tpt_close_browser cancels the browser session while retaining login. After an uncertain submission, inspect the seller account before retrying; the tool deliberately refuses a fresh upload of an already-attempted product.

Only one process can own the dedicated browser profile at a time. Close npm run login before opening the browser from MCP. TPT may default to “Upload thumbnails later” when reopening an edit page; the journal records the mode selected at submission.

For terminal use, run node operator.mjs and enter JSON tool calls, one per line:

{"name":"tpt_list_products","arguments":{}}

Tests

npm test

Tests use temporary synthetic catalogs and a local intercepted browser fixture. They require Chrome, but no TPT login and no real uploads. They cover MCP communication, path confinement, listing validation, file selection, formatting structure, cancellation and thumbnail-mode behavior.

Limitations

• This is a browser adapter: TPT UI changes can require selector updates. The seller form was observed in September 2026.

• Automatic standards-tag and store custom-category selection is not implemented. Keep unsupported arrays empty or complete those fields manually; nonempty values currently stop automatic preparation.

• The current preparation flow expects a paid digital ZIP, PDF preview and four custom thumbnail files. Free resources and other product workflows need additional adaptation.

• Verification confirms saved fields and asset references; it does not compare downloaded asset hashes or prove pedagogical quality.

• Publishing an active listing can trigger TPT's normal follower notifications.

Keep browser sessions, credentials and commercial assets private. Review third-party terms and the product's rights before use.

References: MCP SDK, Playwright file uploads.