Skip to main content
Glama
sakshsiw

Amazon SP-API MCP Server

by sakshsiw
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

SP-API MCP Server Documentation

This document describes the Model Context Protocol (MCP) server for interacting with Amazon's Selling Partner API through natural language.

Developers utilizing this sample solution are solely responsible for its implementation, usage patterns, and must ensure full compliance with all applicable Amazon Selling Partner API Terms of Service, Acceptable Use Policy (AUP), Data Protection Policy (DPP), and any other relevant Amazon policies and agreements. This sample code is provided 'as-is' without any warranties or guarantees.

Overview

The SP-API MCP Server connects Large Language Models to Amazon's Selling Partner API ecosystem. Through conversational interfaces, developers and sellers can explore and execute SP-API operations using natural language.

The server provides:

  • Natural language API exploration and execution

  • Automatic parameter validation and response formatting

  • Code generation in multiple languages

  • OAuth2 token management and request signing

  • Complete SP-API endpoint documentation

Related MCP server: swagger-mcp-server

Data Protection & Privacy

Users must implement appropriate security measures to protect SP-API credentials and any data accessed through this integration. Handle all seller and customer data in accordance with Amazon's Data Protection Policy and applicable privacy laws. Do not store sensitive data in logs or temporary files.

Architecture

The server uses a modular TypeScript architecture:

src/
  index.ts                # Server entry point
  auth/                   # Authentication
  catalog/                # API definitions
  tools/                  # Execution tools  
  types/                  # Type definitions
  utils/                  # Utilities
  config/                 # Configuration

Core Components

  1. MCP Server Core (src/index.ts)

    • Initializes the Model Context Protocol server

    • Registers and manages available tools

    • Handles client communication via stdio transport

  2. Authentication System (src/auth/)

    • Manages OAuth2 token lifecycle

    • Signs requests with proper SP-API authentication headers

    • Handles token refresh automatically

  3. API Catalog System (src/catalog/)

    • Loads and processes OpenAPI/Swagger definitions

    • Creates structured catalog of all SP-API endpoints

    • Provides intelligent endpoint discovery and parameter validation

  4. Tool System (src/tools/)

    • Execute API Tool: Executes authenticated SP-API requests

    • Explore Catalog Tool: Provides endpoint discovery and documentation

Prerequisites

Before setting up the SP-API MCP Server, ensure you have:

  • Node.js 16 or higher

  • Amazon Selling Partner API Credentials:

    • Client ID and Client Secret from Amazon Developer Console

    • Refresh Token from the SP-API authorization flow

    • Proper SP-API application permissions

  • SP-API Model Files

  • MCP-compatible client

Installation

  1. Clone both repositories at the same folder level:

# Clone the models repository first
git clone https://github.com/amzn/selling-partner-api-models.git

# Clone the samples repository  
git clone https://github.com/amzn/selling-partner-api-samples.git

  1. Install and build:

# Navigate to the MCP server
cd selling-partner-api-samples/use-cases/sp-api-mcp-server

# Install and build
npm install
npm run build

Configuration

Configure the SP-API MCP Server by setting environment variables directly in your MCP client's configuration file:

{
  "mcpServers": {
    "amazon-sp-api": {
      "command": "node",
      "args": ["/path/to/selling-partner-api-samples/use-cases/sp-api-mcp-server/build/index.js"],
      "env": {
        // Required Variables
        "SP_API_CLIENT_ID": "your_client_id",
        "SP_API_CLIENT_SECRET": "your_client_secret",
        "SP_API_REFRESH_TOKEN": "your_refresh_token",
        "SP_API_BASE_URL": "https://sellingpartnerapi-na.amazon.com",
        "CATALOG_PATH": "/absolute/path/to/selling-partner-api-models/models",
        
        // Optional Variables
        "MAX_RESPONSE_TOKENS": "25000",
        "LOG_LEVEL": "info",
        "SP_API_OAUTH_URL": "https://api.amazon.com/auth/o2/token"
      }
    }
  }
}

Environment Variables Explained

Required Variables:

  • SP_API_CLIENT_ID: Your Amazon SP-API client ID from Amazon Developer Console

  • SP_API_CLIENT_SECRET: Your Amazon SP-API client secret from Amazon Developer Console

  • SP_API_REFRESH_TOKEN: Your Amazon SP-API refresh token from either Amazon Developer Console(self-authentication) or OAuth authorization flow

  • SP_API_BASE_URL: Amazon SP-API base URL for your marketplace (e.g., https://sellingpartnerapi-na.amazon.com)

  • CATALOG_PATH: Absolute path to the models subdirectory within the cloned selling-partner-api-models repository

CATALOG_PATH Example: If you cloned the repositories to /home/user/projects/, then:

"CATALOG_PATH": "/home/user/projects/selling-partner-api-models/models"

Optional Variables:

  • MAX_RESPONSE_TOKENS: Maximum tokens for API responses (default: 25000)

  • LOG_LEVEL: Logging level - debug, info, warn, or error (default: info)

  • SP_API_OAUTH_URL: Amazon OAuth endpoint (default: https://api.amazon.com/auth/o2/token)

Development

For development work:

npm run dev    # Start with hot reloading
npm test      # Run tests
npm run lint  # Check code style
npm run format # Format code

Available Tools

3 tools
execute-external-apiB

Execute HTTP requests to external REST APIs (non-Amazon APIs)

ParametersJSON Schema
NameRequiredDescriptionDefault
urlYesFull URL of the external API endpoint (required)
bodyNoRequest body (for POST, PUT, PATCH)
methodNoHTTP methodGET
headersNoRequest headers
timeoutNoRequest timeout in milliseconds (default: 30000)
queryParamsNoQuery parameters to append to URL

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden, and it discloses almost nothing: no statement on authentication requirements, whether headers must carry credentials, rate limits, redirect handling, or how responses/errors are surfaced. For a generic outbound HTTP executor this is a substantial gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with zero filler, so every word earns its place. It is arguably too terse for a 6-parameter network tool, but as a conciseness measure it is efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With 6 parameters including nested objects, no output schema, and no annotations, the definition should explain auth requirements, response format, and error behavior. None of that is present, leaving an agent without the context needed to call this outbound-request tool safely.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% and every parameter (url, body, method, headers, timeout, queryParams) is documented in the schema, so baseline 3 applies. The description adds no extra meaning such as body serialization format or how headers interact with auth.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (Execute) and resource (HTTP requests to external REST APIs), and the parenthetical '(non-Amazon APIs)' meaningfully scopes it away from the sibling execute-sp-api. It stops short of naming the alternative tool outright, but an agent can still route correctly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The '(non-Amazon APIs)' qualifier implies when to use this over execute-sp-api, but there is no explicit when-to-use rule, no mention of prerequisites (credentials, auth setup), and no exclusion beyond the Amazon boundary. Usage is inferable but not stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

execute-sp-apiC

Execute Amazon Selling Partner API requests with specified endpoint and parameters

ParametersJSON Schema
NameRequiredDescriptionDefault
methodNoHTTP method
regionNoAWS region for the requestus-east-1
rawModeNoReturn raw response if true
endpointYesThe specific SP-API endpoint to use (required)
parametersYesComplete set of API parameters
generateCodeNoGenerate code snippet if true
additionalHeadersNoAdditional request headers

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden, yet it discloses nothing about authentication needs, rate limits, error behavior, or the fact that GET/POST/PUT/DELETE have very different side effects (including destructive ones). For a generic API execution tool with mutation methods, this is a significant gap.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single efficient sentence with no filler, appropriately front-loaded with the verb and resource. It is not padded, though it is arguably under-specified rather than genuinely concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter passthrough tool with nested objects, no output schema, and no annotations, the description omits nearly everything an agent needs: what the response looks like, what rawMode or generateCode actually change, and what auth/region setup is assumed. It is too thin for the tool's complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents endpoint, method, region, rawMode, parameters, generateCode, and additionalHeaders. The description only restates 'specified endpoint and parameters' and adds no format, constraints, or examples beyond the schema. Baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (Execute) and resource (Amazon Selling Partner API requests), which is clear and materially more specific than the generic sibling execute-external-api. It does not explicitly contrast itself with explore-sp-api-catalog or execute-external-api, so it stops short of a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to choose this tool over execute-external-api or explore-sp-api-catalog, nor any mention of prerequisites such as credentials or the fact that this is a raw passthrough executor. Usage is left entirely to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

explore-sp-api-catalogC

Get information about SP-API endpoints and parameters

ParametersJSON Schema
NameRequiredDescriptionDefault
refNoExtract specific nested object using dot notation (e.g., 'Order.ShippingAddress')
depthNoControl nested object expansion depth. When NOT specified, defaults to 'full' (complete expansion). REQUIRED: Must be either a number (0, 1, 2, 3, etc.) for specific depth levels, or the string 'full' for complete expansion. Invalid values like null, undefined, or empty strings will cause errors. IMPORTANT: Omit this parameter entirely for full expansion - do NOT pass null or undefined.full
categoryNoCategory to explore
endpointNoSpecific endpoint to get details for
listEndpointsNoList all available endpoints
listCategoriesNoList all available categories

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral burden. It only says 'Get information' and discloses nothing about read-only safety, response format, limits, or how the listEndpoints/listCategories flags interact with category/endpoint.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, front-loaded sentence with no filler. It is efficient, though arguably under-specified rather than optimally sized for a six-parameter tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With six parameters, no annotations, and no output schema, the agent needs more than 'Get information about SP-API endpoints and parameters.' The description leaves the catalog-browsing workflow (how to list categories/endpoints, what the ref/depth options apply to) entirely to the schema.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents all six parameters (including dot-notation ref, depth semantics, and category/endpoint). The description adds no parameter meaning beyond that, so the baseline of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a clear verb-and-resource: retrieve information about SP-API endpoints and parameters. It implicitly contrasts with the execute-* siblings (exploration vs execution), though it never names them or explicitly draws that line.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No when-to-use, when-not-to-use, or alternative-tool guidance. The description does not tell the agent whether this should be called before execute-sp-api, or how it relates to execute-external-api.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 3 tool updatesv0.1.0
    • First observedexecute-external-api
    • First observedexecute-sp-api
    • First observedexplore-sp-api-catalog
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 3 tools

Disambiguation4/5

The three tools have distinct purposes: one executes SP-API calls, one explores the SP-API catalog, and one executes external APIs. The only potential overlap is between execute-sp-api and execute-external-api, but the domain distinction (Amazon vs non-Amazon) is clearly stated in descriptions.

Naming Consistency5/5

All tool names follow a consistent kebab-case verb-noun pattern: execute-sp-api, explore-sp-api-catalog, execute-external-api. The verb choices (execute, explore) are appropriate and predictable.

Tool Count4/5

Three tools is a reasonable minimum for a generic API gateway that covers execution and discovery. However, the external API tool feels slightly out of scope for an Amazon SP-API server, making the set a bit ad hoc rather than perfectly scoped.

Completeness4/5

The combination of execute-sp-api and explore-sp-api-catalog provides complete coverage for generic SP-API interactions: discovery and execution. There are no obvious gaps for the stated purpose, though dedicated helpers for common operations are absent and the external API tool is extraneous.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • swagger-mcp-server

    maohuihua123
    A
    license
    Not graded
    quality
    D
    maintenance
    Enables natural language interaction with any Swagger/OpenAPI-defined API, allowing discovery, parameterized calls, and automated testing through large language models.
    5
    Apache 2.0

  • Amazon Seller MCP Server

    trinknx
    A
    license
    Not graded
    quality
    C
    maintenance
    Exposes Amazon Selling Partner API tools for sellers to manage orders, inventory, listings, pricing, analytics, and reports via natural language.
    15 npm
    1
    AGPL 3.0

  • Amazon Seller MCP

    thecoolcompanysl
    F
    license
    A
    quality
    C
    maintenance
    Connects Claude to your Amazon Seller Central account via the Selling Partner API, enabling queries for recent orders, sales summaries, FBA inventory, and financial events.
    4
    -