TD SYNNEX MCP

TD SYNNEX + AI - for Claude, the ChatGPT desktop app, GitHub Copilot, Gemini CLI, and any agent that speaks MCP

Unofficial. Community-built Claude Code Skill and MCP server for the TD SYNNEX API. Not affiliated with, endorsed by, or sponsored by TD SYNNEX Corporation.

[TD SYNNEX StreamOne ION demo - animated preview]

_{▶ Watch the 30-second demo - demo data is simulated; every command shown exists in the real CLI.}

Every StreamOne ION reseller API, plus a local licence book for renewals, margin and cross-distributor true-up. Works with the AI you already use - Claude Desktop, Codex, Claude Code, Claude Cowork, and GitHub Copilot, no code required - plus the ChatGPT desktop app and Gemini CLI. Free, open source, runs on your laptop. Built for MSP owners.

Works with your agent

The agents MSP owners use most (self-serve, works today):

Also for ChatGPT and the Microsoft and Google stacks

Big install base, but an honest heads-up: Gemini CLI runs the local binary you just installed, while Microsoft 365 Copilot and the Gemini app need a remote server, which msp-skills does not support yet.

Skill-native agents (also covered): Hermes and OpenClaw read this skill's SKILL.md directly and speak MCP - see their install sections below. Also works with Cursor, Windsurf, Cline, Continue.dev, and Zed via MCP. Full per-tool wire-up: docs/which-agent.md.

Run more than one agent? Install across all 51+ supported agents in one command: npx skills add Servosity/msp-skills@latest (requires Node.js, then run the per-skill installer for the CLI/MCP binaries). See docs/which-agent.md.

Install in 60 seconds

Fastest for Claude Desktop - one-click .mcpb

Download TD SYNNEX MCP (.mcpb) - then open Claude Desktop > Settings > Extensions and select the file. One click, no JSON. ION needs one shell step first: install the CLI (Path B below) and run td-synnex-cli auth mint --refresh-token-stdin once (see Authenticate); the extension reads the token it saves. (Browse every TD SYNNEX release on the releases page.)

Prefer the Claude Code plugin? Add the marketplace once, then install - works immediately, no directory listing required:

/plugin marketplace add Servosity/msp-skills/plugin install td-synnex@msp-skills

Path A - paste one prompt into your AI agent (recommended)

Copy this into Claude Code, Codex CLI, or Claude Cowork:

Install the TD SYNNEX Skill and MCP server from Servosity/msp-skills in this agent workspace. If this workspace uses a POSIX shell (macOS, Linux, WSL, or Bash), run bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/td-synnex/install.sh). If it uses Windows PowerShell, run iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/td-synnex/install.ps1 | iex. Then authenticate per the README and run td-synnex-cli --help to explore.

The same prompt works in any agent that can run shell.

Path B - run the installer yourself

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/td-synnex/install.ps1 | iex

macOS / Linux:

bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/td-synnex/install.sh)

The installer drops both td-synnex-cli (the CLI) and td-synnex-mcp (the MCP server) into your user bin path. Claude Code, Codex, and Cowork discover the Skill via SKILL.md in this directory.

Verify:

td-synnex-cli --version

Upgrade to the latest version

The installer always fetches the current release - re-run it to upgrade:

macOS / Linux:

bash <(curl -fsSL https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/td-synnex/install.sh)

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/Servosity/msp-skills/main/skills/td-synnex/install.ps1 | iex

Claude Desktop .mcpb users: download the latest .mcpb (top of this section) and re-select it in Settings > Extensions. Claude Code plugin users: /plugin update td-synnex@msp-skills.

Add to Claude Desktop, the ChatGPT desktop app, GitHub Copilot, Gemini CLI, or another MCP client

After the installer runs, see mcp-install.md and docs/which-agent.md for the per-agent wire-up - one section per agent, including the GitHub Copilot servers key and the ChatGPT desktop app. Claude Desktop's Settings > Extensions panel is the simplest path; the MCP config block (for users who prefer editing JSON) is documented in mcp-install.md.

Install for Hermes

From the Hermes CLI:

hermes skills install servosity/msp-skills/skills/td-synnex --force

Inside a Hermes chat session:

/skills install servosity/msp-skills/skills/td-synnex --force

Hermes speaks MCP natively, so it can also use the td-synnex-mcp server directly - same install path, same env vars.

Install for OpenClaw

Tell your OpenClaw agent (copy this):

Install the td-synnex skill from https://github.com/servosity/msp-skills/tree/main/skills/td-synnex. The skill defines how its required CLI (td-synnex-cli) can be installed via the openclaw: frontmatter block.

OpenClaw isn't generally available yet; the frontmatter wiring is pre-shipped and will activate the moment OpenClaw launches.

Authenticate

StreamOne ION signs you in with an OAuth refresh token. In the ION portal open Settings > Users > Edit > OAuth credentials > Request New Credentials and copy the refresh token. Then set your ION account ID and hand the token to auth mint on stdin, so it never lands in shell history:

macOS / Linux:

export TD_SYNNEX_ACCOUNT_ID=<your ION account ID>   # also add this line to your shell profile (~/.zshrc or ~/.bashrc)pbpaste | td-synnex-cli auth mint --refresh-token-stdin   # Linux: xclip -o -selection clipboard | td-synnex-cli auth mint --refresh-token-stdintd-synnex-cli auth check

Windows (PowerShell):

setx TD_SYNNEX_ACCOUNT_ID "<your ION account ID>"   # persists for new windows$env:TD_SYNNEX_ACCOUNT_ID = "<your ION account ID>"  # this windowGet-Clipboard | td-synnex-cli auth mint --refresh-token-stdintd-synnex-cli auth check

Keep TD_SYNNEX_ACCOUNT_ID set permanently: the local store is keyed on it, and without it every new 2-hour access token starts an empty store.

ION refresh tokens are single-use and last 32 days; access tokens last 2 hours. auth mint exchanges the token, saves the new access token and the new refresh token to a private credentials file before it prints anything, and never prints a token (--print-access-token prints a withheld notice; read the token from the credentials file instead). Keep it fresh from cron or Task Scheduler with td-synnex-cli auth mint --if-expiring 15m. auth check asks ION how long both tokens stay valid. Do not give the refresh token to auth set-token, which stores an access token.

Then pull your book into the local store and confirm the numbers against the portal:

td-synnex-cli sync --resources customers,subscriptions,orderstd-synnex-cli doctor

What this skill does

subscriptions set only previews the order; add --confirm to place it. The licence-book commands (renewals, changes, margin, position, orders stuck, customers show) read the local store, so run sync first. position trueup --with and --billed read export files from your disk, so they run where your agent has a shell (Claude Code, Codex, Cowork) or in your terminal; over MCP (Claude Desktop, ChatGPT, Copilot) the tool refuses file paths and only lists SKUs a customer holds in more than one TD SYNNEX subscription.

Full command reference: guide.md. For the AI-agent operating contract (--agent, --dry-run, when to confirm before mutating), see AGENTS.md.

What makes this different

Most StreamOne ION integrations are PSA billing connectors or API wrappers that make one live call per question. That's fine for one record. It dies at scale, when you're asking "which of my 60 customers have NCE terms renewing this month with auto-renew off, and what do I make on each of them".

This skill syncs TD SYNNEX into a local SQLite mirror with full-text search. Aggregate questions become one local SQL join: instant, offline, and the AI sees the answer, not the raw data. Compound commands like subscriptions renewals, margin and position trueup join across customers, subscriptions, orders and your Pax8, Sherweb or PSA exports - work a stateless API wrapper can't do. It complements the ION portal and TD SYNNEX's PSA connectors rather than replacing them: ordering, provisioning and billing sync stay there.

The pain this closes

Microsoft's New Commerce terms only let you cut seats or cancel in the first seven days of a term or a renewal. Miss the renewal and you carry another year of seats the client may no longer pay for. The tminus365 blog for MSPs (How I automated subscription renewal notices for Microsoft NCE, 2022) describes building a Power Automate flow on a distributor API just to open a ticket before each renewal. Add a second distributor and the seat counts you pay for sit in two portals plus the PSA agreement you bill from.

• Renewals before the window closes: td-synnex-cli subscriptions renewals --within 30d --auto-renew off lists every term renewing soon, soonest first.
• Customers sold at a loss: td-synnex-cli margin --by customer ranks customers worst margin first and flags negative, zero and below-list-price rows.
• Seats you pay for but never bill: td-synnex-cli position trueup --billed psa-agreements.csv compares ION seats with your PSA export and flags each mismatch (billed_mismatch), and paid seats no PSA row bills at all (not_billed; trial seats are flagged trial instead).
• Orders nobody noticed: td-synnex-cli orders stuck lists orders still open after a day, and orders that failed.

See pain-point.md for the longer narrative.

Frequently asked questions

Does this work with ChatGPT?

Yes, in the ChatGPT desktop app. It runs MCP servers locally (STDIO), the way td-synnex-mcp runs, and shares MCP configuration with Codex (OpenAI): add td-synnex-mcp under Settings > MCP servers as a STDIO server, or add it once to Codex's ~/.codex/config.toml. ChatGPT on the web is not supported by msp-skills yet: it needs a remote server. If your team works there, a hosted gateway is the better pick; check that your AI app is on the gateway's setup list. Setup steps: mcp-install.md.

Does this work with Codex, Cursor, Windsurf, Cline, Copilot, or Gemini?

Yes - all of them speak MCP. Cross-tool install commands are in the matrix above and the deep-dive in docs/which-agent.md.

Do I need to know how to code?

No. The recommended install is to paste one sentence into Claude Code or Codex - your agent reads SKILL.md and does the install. The fallback is a one-line installer per OS (bash or PowerShell). Neither path requires writing code. You'll enter your TD SYNNEX credentials once.

Is my TD SYNNEX data safe?

Your data stays on your machine. The CLI and MCP server are local binaries. The SQLite mirror sits in a directory under your user account. The AI agent only sees what the CLI returns - typically a query result, not raw bulk data. Your ION tokens live in a private credentials file under your user account (or in TD_SYNNEX_ACCESS_TOKEN if you prefer); they are never bundled into this repo or transmitted anywhere by MSP Skills. Passwords ION returns inside customer, order and provisioning data (customer user passwords, Microsoft tenant admin credentials) are blanked in every response before anything is printed, cached, synced or handed to an agent. Free text (notes, descriptions, report CSV) is withheld whole when it mentions a credential word such as password, PIN, secret, token or API key anywhere, so a note or a reports get-data-csv result that merely mentions one (a "Duo Hardware Token" row, say) comes back as [redacted]; reports get-data returns the same report cell by cell, and name, ID and address fields use a narrower rule so customer and catalog names and SKUs survive. A password typed into a note with no credential word near it cannot be recognized.

How does it sign in to StreamOne ION?

With an ION OAuth refresh token, which needs an ION reseller account. Request it in the portal under Settings > Users > Edit > OAuth credentials > Request New Credentials and pipe it to td-synnex-cli auth mint --refresh-token-stdin. ION refresh tokens are single-use, so auth mint saves the rotated token before printing anything; if that save fails it writes the new refresh token to a private rescue file so you are not locked out. See Authenticate.

Will this hit my ION API limits?

subscriptions renewals, subscriptions changes, margin, position export, position trueup, orders stuck and customers show answer from the local store. When the store is stale they first refresh the first page (about 100 rows) of each resource they read, so with a larger book run td-synnex-cli sync before whole-book answers; add --data-source local (or set TD_SYNNEX_NO_AUTO_REFRESH=1) to never call the API from them. Live calls respect the --rate-limit throttle.

Can it change subscriptions or place orders?

Yes, and that is why the safety model matters. subscriptions set previews the UPDATE order and places it only with --confirm. Other writes (carts checkout, customer-orders create-order and cancel-order, customers create and update) send as soon as they run; preview them with --dry-run first. Over MCP, every tool that can change ION previews and sends only when the agent repeats the call with confirm set to true. Set TD_SYNNEX_MCP_READ_ONLY=1 to keep the MCP server to reads.

Are the margin numbers exact?

Not yet proven. See Known gaps.

Does this replace the ION portal?

No. Ordering, provisioning and invoicing stay in StreamOne ION. This skill answers the questions that span every customer, from your terminal or agent.

What does it cost?

Free. Apache-2.0 licensed. You pay only for whichever AI agent you use (Claude, ChatGPT, Codex, etc.), and that's billed by your AI provider, not by us.

Safety model

TD_SYNNEX_MCP_READ_ONLY=1 removes every tool that can change ION from the MCP server; it also removes sync and the tools that record learnings, and the tools it keeps still write local state (the synced store when a read refreshes it, the command journal and recall statistics).

The strongest control is the ION user whose OAuth credentials you issue - the CLI can only do what that user is permitted to do. Full details, including how to lock it down, are in governance.md.

Known gaps

• Not yet run against a live StreamOne ION tenant. Every command was checked against TD SYNNEX's published v3 API documentation, a mock ION server and unauthenticated route probes, not real account data. Start with td-synnex-cli doctor and a small td-synnex-cli sync --resources customers, and compare the first results with the ION portal.
• Margin assumes ION prices per subscription, not per seat. margin, subscriptions renewals, position export and customers show use the price and cost ION reports for each subscription (for monthly billing, its newest billed month) and do not multiply them by seats. If ION reports them per seat, multi-seat totals are understated, and so is position trueup's unit_cost_by_source (cost divided by seats), by the same factor. Compare one multi-seat subscription with the ION portal before relying on the totals. A price, cost, seat count, order quantity, order total or order age ION does not send (or sends in a form the CLI cannot read; the record is kept, except that a subscription or order whose status, trial flag or customer ID is unreadable is skipped with a warning, and subscriptions set refuses to order from a subscription whose IDs, owner, status, flags or dates it cannot read), or a billing cycle the CLI does not recognize (the commitment term is never used in its place), is reported as unknown (price_known, cost_known, seats_known, or a *_incomplete flag), never as 0, and is left out of totals and margin. When an annual subscription sends neither price nor cost, the trailing twelve billed months are summed, so a subscription that switched from monthly to annual billing inside that window counts both; basis names the months used.
• Changes made outside ION are invisible. subscriptions changes decodes ION orders, so a seat change made directly in Microsoft Partner Center does not appear.
• Generated passwords are not shown. customers create and cloud-providers provision-customer blank the one-time password ION returns, along with every other credential in ION responses. Set or reset that password in the ION portal or the Microsoft 365 admin center.
• Tenant ID and domain are blank in position export. ION subscriptions do not carry them, so position trueup matches customers on name unless your other files supply them.

Status

Beta. Checked against TD SYNNEX's published v3 API documentation and a mock ION server, not yet against a live tenant (see Known gaps). We validate connectors with MSPs running them live against their own production tenants in our weekly Build Sessions. RSVP at compoundingteams.com/build-sessions.

Standards. Conforms to the open Agent Skills spec (Anthropic, Dec 2025; 40+ agents). MCP-compatible - works with any MCP-capable agent including Hermes. OpenClaw-ready (frontmatter pre-wired, awaiting OpenClaw launch).

Maintained by Servosity. Apache-2.0 licensed. Built with CLI Printing Press. Last updated: 2026-10-16.