Tradly MCP Server

An MCP (Model Context Protocol) server that connects the Tradly Marketplace API with MCP-compatible clients such as ChatGPT Desktop, Claude Desktop, Codex, and other MCP hosts.

This package makes it easy to query products, categories, accounts, reports, and a much broader set of Tradly admin and commerce endpoints directly inside your MCP-enabled environment.

Features

• MCP-compatible server for Tradly.
• Fetch products and product details.
• Get listing categories.
• Search accounts and stores.
• Create listings and blog posts when write access is enabled.
• Search users, fetch user details, and send email from the same MCP surface.
• Create and manage collections for curated content workflows.
• Manage coupons when the tenant supports the coupon endpoint.
• Reach additional Tradly endpoints through the generic tradly_request tool when you need raw access to an Istanbul-style endpoint that is not wrapped yet.
• OAuth bearer-token authentication or a Tradly x-auth-key session token.
• Node.js 18+ ready.
• Stdio MCP server for local MCP clients.
• HTTP MCP server for hosted deployments.
• Streamable HTTP and legacy SSE transport support.
• OAuth discovery endpoints for hosted clients.

Installation

npm install -g @tradly/mcp

Local Stdio Usage

Before running, set your Tradly API access token. Use a server-side Tradly bearer token or Tradly x-auth-key session token for local stdio usage.

Keys can be found in your Tradly SuperAdmin under Settings/API.

export TRADLY_API_KEY=your_tradly_access_token
@tradly/mcp

If everything is set up correctly, the process starts on stdio and logs:

Tradly MCP server running on stdio

Connect To An MCP Client

Add this to your MCP client config:

{
  "servers": {
    "tradly": {
      "command": "@tradly/mcp",
      "env": {
        "TRADLY_API_KEY": "your_tradly_access_token"
      }
    }
  }
}

Restart your MCP client, then ask natural-language questions such as:

• "Get categories from Tradly"
• "Search accounts for electronics stores"
• "Find products matching milk"
• "Create a test listing in my Tradly store"

Hosted HTTP Usage

Run locally:

npm install
npm run start:http

The HTTP MCP endpoint is:

http://localhost:3000/api/mcp

Production manifest endpoint:

https://mcp.tradly.app/.well-known/mcp/manifest.json

Environment Variables

• TRADLY_API_KEY: Tradly access token used by stdio mode.
• TRADLY_AUTH_KEY: Optional Tradly x-auth-key session token override for stdio mode.
• TRADLY_BASE_URL: Tradly app/API base URL. Defaults to https://api.tradly.app.
• TRADLY_OAUTH_BASE_URL: Tradly OAuth base URL. Defaults to https://skua.tradly.app.
• TRADLY_EMAIL_AUTH_KEY: Auth key used by the email utility endpoint. Falls back to TRADLY_API_KEY when unset.
• SENTRY_DSN: Optional Sentry DSN to enable error reporting.
• SENTRY_ENVIRONMENT: Optional Sentry environment name.
• SENTRY_TRACES_SAMPLE_RATE: Optional tracing sample rate between 0 and 1.
• SENTRY_RELEASE: Optional release identifier for Sentry.
• TRADLY_CLIENT_ID: OAuth client ID for hosted callback token exchange.
• TRADLY_CLIENT_SECRET: OAuth client secret for hosted callback token exchange.
• TRADLY_REDIRECT_URI: OAuth redirect URI for hosted callback token exchange.
• PORT: HTTP server port. Defaults to 3000.
• LOG_MCP_REQUESTS: Set to false to disable HTTP MCP request logs.
• MCP_LOG_LEVEL: Log level for structured MCP logs. Defaults to info.
• MCP_LOG_FORMAT: Set to pretty for human-readable console logs. Defaults to JSON lines.
• MCP_LOG_FILE: Optional file path for persisted JSONL logs.
• MCP_LOG_FILE_MAX_BYTES: Maximum size in bytes before rotating MCP_LOG_FILE. Defaults to 5242880.
• MCP_LOG_FILE_MAX_BACKUPS: Number of rotated log files to keep. Defaults to 3.
• MCP_LOG_VIEWER: Set to false to disable the local browser log viewer.

Logs are written to stderr so stdio MCP clients do not receive protocol-breaking output on stdout.

Local Log Viewer

When running the HTTP server locally, open:

http://localhost:3000/logs

The page polls the recent log buffer and listens to /api/logs/stream for live updates.

Tools

The following tools are available once connected to an MCP client.

get_products

Fetch products/listings from the marketplace.

Parameters:

• page number, default 1
• per_page number, default 30
• price_from number, optional
• price_to number, optional
• search_key string, optional
• sort string, optional
• category_id string, optional
• account_id string, optional
• attribute_value_id string, optional

get_product_details

Get details for a specific product/listing.

Parameters:

• listingId string, required

search_accounts

Search accounts/stores in the marketplace.

Parameters:

• page number, default 1
• type string, default accounts
• per_page number, default 20
• category_id string, optional
• user_id string, optional
• search_key string, optional
• latitude number, optional
• longitude number, optional
• max_distance number, optional
• status number, optional

get_categories

Fetch available categories.

Parameters:

• type string, default listings
• parent string, default 0

create_listing

Create a new product listing.

Required parameters:

• title
• description
• price
• category_id
• account_id

Optional parameters include currency_id, images, stock, offer_percent, coordinates, type, order_type, and attributes.

create_blog_post

Create a blog post using the Layers API.

Required parameters:

• title
• content

Optional parameters include tags, slug, account_id, and published.

send_email

Send an email through Tradly's utility endpoint.

Required parameters:

• subject
• body
• email
• email_type

email must be an array of recipient addresses.

search_users

Search Tradly users by keyword.

Parameters:

• page number, optional
• per_page number, optional
• sort string, optional
• search string, optional
• blocked boolean, optional

Use this together with get_user_details or get_user_profile when you need a specific person before sending an email.

get_collections

List collections.

Parameters:

• page number, optional
• per_page number, optional
• scope_type number, optional

create_collection

Create a collection.

Required parameters:

• collection

update_collection

Update a collection.

Required parameters:

• collectionId

get_coupons

List coupons.

Parameters:

• page number, optional
• per_page number, optional

create_coupon

Create a coupon.

Required parameters:

• coupon
• collection

delete_collection

Delete a collection.

Required parameters:

• collectionId

tradly_request

Send a raw request to a Tradly endpoint.

Parameters:

• path string, required
• method string, default GET
• base string, default api
• auth_mode string, default bearer
• query object, optional
• body object, optional
• headers object, optional

Use this for Tradly endpoints that are present in the Istanbul app but not yet wrapped as first-class MCP tools.

get_reports

Generate delivery reports.

Parameters:

• type string, default orders

Write tools create real Tradly records. For release testing, use test names prefixed with MCP_PUBLIC_TEST_DO_NOT_USE.

Release Checks

npm test
npm run pack:dry-run

The release checks verify:

• package metadata and binary name
• manifest and tool registry consistency
• stdio MCP initialize/tools/list/tool-call flow
• HTTP MCP well-known endpoints and streamable HTTP flow
• basic error behavior without needing live write calls

Live API checks require a valid Tradly access token:

TRADLY_API_KEY=your_tradly_access_token npm test

Run live Tradly tool checks:

TRADLY_API_KEY=your_tradly_access_token npm run test:live

Run live write checks only when you have a disposable account/category:

TRADLY_API_KEY=your_tradly_access_token \
LIVE_WRITE=true \
TEST_ACCOUNT_ID=123 \
TEST_CATEGORY_ID=456 \
npm run test:live

Development

npm install
npm run test:static
npm run test:stdio
npm run test:http

Contributing

Pull requests are welcome. Please open an issue first for major changes so the expected MCP behavior and Tradly API surface can be discussed.

Keywords

mcp model-context-protocol tradly marketplace server sdk