MCP Servers

模型上下文协议服务器、框架、SDK 和模板的综合目录。

S
Sp Api MCP Go
作者 @berrydev-ai
GitHub 仓库(1 星标)

MCP server by berrydev-ai

创建于 9/29/2025
更新于 3 months ago
README
View Source
Repository documentation and setup instructions

Selling Partner API MCP Server (Go)

This project packages Amazon's Selling Partner API into a Model Context Protocol (MCP) server written in Go. The server uses mark3labs/mcp-go for the transport/runtime layer and amzapi/selling-partner-api-sdk for SP-API clients. The implementation includes live integrations for Orders, Sales, Reports, FBA Inventory, and Product Pricing APIs, with additional endpoints planned (see TODO checklist below).

Table of Contents

Overview

An MCP server that exposes Amazon Selling Partner API operations as tools for AI assistants. Supports multiple transport modes (stdio, SSE, Streamable HTTP) for integration with various MCP clients including Cursor, Claude Desktop, and Continue.

Current Status: Active development with 12+ implemented endpoints including order management, sales metrics, reporting, inventory summaries, and pricing information.

Technology Stack

  • Language: Go 1.22+
  • Package Manager: Go modules
  • Key Dependencies:
    • mark3labs/mcp-go v0.39.1 - MCP protocol implementation
    • amzapi/selling-partner-api-sdk - Amazon SP-API client library
    • joho/godotenv v1.5.1 - Environment variable management
    • google/uuid v1.6.0 - UUID generation

Prerequisites

  • Go 1.22 or newer
  • Amazon Selling Partner API credentials (Login with Amazon) with access to the desired marketplaces
  • Optional .env file in the repository root so secrets stay out of your shell history

Keep credentials secure; never commit them to source control. Rotate refresh tokens regularly and scope IAM roles to the minimum permissions your workflow requires.

Configuration

The server reads configuration from environment variables (or a local .env file). Defaults are chosen for local development, but production deployments should set every value explicitly.

| Variable | Default | Description | | --- | --- | --- | | SP_API_CLIENT_ID | required | Login with Amazon client identifier | | SP_API_CLIENT_SECRET | required | Login with Amazon client secret | | SP_API_REFRESH_TOKEN | required | Refresh token scoped to your SP-API role | | SP_API_ENDPOINT | https://sellingpartnerapi-na.amazon.com | SP-API regional endpoint | | MCP_SERVER_NAME | Selling Partner MCP Server | Name shown to MCP clients | | MCP_SERVER_VERSION | 0.1.0 | Semantic-ish version string reported to clients | | MCP_SERVER_INSTRUCTIONS | placeholder text | High-level instructions shared with the assistant | | MCP_TRANSPORT | stdio | One of stdio, sse, streamablehttp | | PORT | 8080 | Required when using sse or streamablehttp transports |

Example .env template:

SP_API_CLIENT_ID=amzn1.application-oa2-client....
SP_API_CLIENT_SECRET=super-secret
SP_API_REFRESH_TOKEN=Atzr|...
SP_API_ENDPOINT=https://sellingpartnerapi-na.amazon.com
MCP_TRANSPORT=stdio

Quick Start

# install dependencies & verify the project builds
go build ./...

# run the MCP server over stdio (default)
go run ./cmd/server

When MCP_TRANSPORT is left as stdio, the process communicates via stdin/stdout and is ideal for desktop MCP clients like Cursor or Claude. To expose it as a network service, pick an alternate transport:

# SSE endpoint on localhost:8080
PORT=8080 MCP_TRANSPORT=sse go run ./cmd/server

# Streamable HTTP endpoint on localhost:9090
PORT=9090 MCP_TRANSPORT=streamablehttp go run ./cmd/server

Build a reusable binary if you plan to host it somewhere persistent:

go build -o bin/sp-api-mcp ./cmd/server

Available Commands

The project includes a Makefile with several convenience targets for development:

# Run development server with HTTP transport on port 8002
make dev-http

# Run development server with SSE transport on port 8002
make dev-sse

# Run MCP Inspector for debugging tool interactions
make inspector

Manual Commands

# Build the project
go build ./...

# Run tests
go test ./...

# Build production binary
go build -o bin/sp-api-mcp ./cmd/server

# Run the server directly
go run ./cmd/server

Registering the Server with an MCP Client

The server can be launched by any MCP-compatible client by delegating to the go run command (or a compiled binary) and exporting the required environment variables.

Cursor

Add an entry to ~/Library/Application Support/Cursor/mcp.json (macOS) or the equivalent path on your platform:

{
  "mcpServers": {
    "sp-api": {
      "command": "go",
      "args": ["run", "./cmd/server"],
      "cwd": "/absolute/path/to/sp-api-mcp-go",
      "env": {
        "SP_API_CLIENT_ID": "amzn1.application-oa2-client...",
        "SP_API_CLIENT_SECRET": "...",
        "SP_API_REFRESH_TOKEN": "Atzr|...",
        "SP_API_ENDPOINT": "https://sellingpartnerapi-na.amazon.com"
      }
    }
  }
}

Restart Cursor and enable the sp-api server in the MCP panel.

Claude Desktop

Create or update ~/Library/Application Support/Claude/mcp/config.json (macOS) with the server configuration:

{
  "servers": {
    "sp-api": {
      "command": "/absolute/path/to/bin/sp-api-mcp",
      "transport": "stdio",
      "workingDirectory": "/absolute/path/to/sp-api-mcp-go",
      "env": {
        "SP_API_CLIENT_ID": "amzn1.application-oa2-client...",
        "SP_API_CLIENT_SECRET": "...",
        "SP_API_REFRESH_TOKEN": "Atzr|..."
      }
    }
  }
}

Restart Claude Desktop to pick up the new configuration. If you prefer to run over SSE or Streamable HTTP, point command to a process supervisor (e.g. npm, systemd, forever) that hosts the binary and then reference the network endpoint inside Claude's UI when adding the server.

Other MCP Clients

  • Continue: add a stanza under ~/.continue/mcpServers.json using the same structure as above.
  • Runes/CLI tools: invoke the binary directly and pipe stdin/stdout, or configure the client to connect to the SSE/HTTP endpoint depending on your transport choice.

Regardless of the client, make sure the process can read your .env or has the credentials in its environment before starting.

Tools & Resources Exposed

The current build ships placeholder tools to help you scaffold real SP-API workflows:

  • auth.beginAuthorization – Guides implementing Login with Amazon authorization.
  • catalog.lookupItem – Placeholder for catalog metadata lookups.
  • inventory.getSummary – Placeholder for inventory summaries across marketplaces.
  • orders.listOrders – Lists orders for a marketplace window and returns Amazon next tokens for pagination.
  • orders.getOrder – Fetches order metadata and line items via the Orders API when SP-API credentials are configured.
  • orders.getOrderAddress – Returns the shipping address for an order.
  • orders.getOrderBuyerInfo – Returns buyer contact details where scopes allow it.
  • orders.getOrderItems – Lists order line items page by page.
  • orders.getOrderItemsBuyerInfo – Lists buyer-specific data such as gift messages per line item.
  • reports.createReport – Placeholder for asynchronous report generation.
  • feeds.submitFeed – Placeholder for feed submission workflows.
  • finance.listFinancialEvents – Placeholder for reconciling financial events.
  • notifications.subscribe – Placeholder for managing notification subscriptions.
  • pricing.getPricing – Placeholder for competitive pricing retrieval.
  • listings.updateListing – Placeholder for listing patch operations.
  • fba.createInboundShipmentPlan – Placeholder for FBA inbound shipment planning.

Documentation resources are available under URIs like amazon-sp-api://overview, providing structured notes you can expand with live references as integrations are implemented.

Testing

Run the test suite to ensure code quality:

# Run all tests
go test ./...

# Run tests with verbose output
go test -v ./...

# Run tests with coverage
go test -cover ./...

Current test coverage: Tests exist for sales API operations (internal/tools/sales_test.go). Additional test coverage for other API endpoints is planned.

Project Structure

.
├── cmd/
│   └── server/          # Main entry point (main.go)
├── internal/
│   ├── app/             # MCP server setup and middleware
│   ├── config/          # Configuration loading and validation
│   ├── resources/       # MCP resource definitions
│   ├── spapi/           # SP-API client wrapper
│   └── tools/           # MCP tool implementations
│       ├── orders.go              # Orders API tools
│       ├── sales.go               # Sales API tools  
│       ├── reports.go             # Reports API tools
│       ├── fba_inventory.go       # FBA Inventory tools
│       ├── product_pricing.go     # Product Pricing tools
│       ├── *_decode.go            # Response decoders
│       ├── registry.go            # Tool registration
│       └── specs.go               # Tool specifications
├── __reference/         # Reference SP-API SDK implementation
├── bin/                 # Compiled binaries (gitignored)
├── config.example.json  # Example MCP client configuration
├── .env                 # Local environment variables (gitignored)
├── go.mod               # Go module definition
├── Makefile             # Development convenience commands
└── README.md            # This file

Key Components:

  • Entry Point: cmd/server/main.go - Loads configuration, initializes SP-API client, starts MCP server
  • Configuration: internal/config/ - Environment-based configuration with validation
  • SP-API Client: internal/spapi/ - Wraps the amzapi SDK with credential management
  • Tools: internal/tools/ - Individual SP-API operations exposed as MCP tools
  • Resources: internal/resources/ - Documentation resources for the MCP protocol

Development Workflow

  • Format code with gofmt (tabs, trailing newline).
  • Run go test ./... before pushing changes.
  • go run ./cmd/server exercises the server end-to-end against your environment.
  • Generated binaries (bin/sp-api-mcp or similar) should remain untracked; rebuild locally when needed.

Feel free to replace placeholder tool implementations with real SP-API calls by extending the types under internal/tools and wiring additional dependencies through internal/app.

Troubleshooting

  • Configuration errors: the server validates environment variables on startup and will explain missing or partial credentials in the log output.
  • Authentication failures: confirm your refresh token is still valid and that the IAM role has the scopes required by the requested SP-API endpoints.
  • Rate limits: Amazon enforces per-endpoint throttling; cache responses and implement retries with backoff when you replace the placeholder logic with live calls.

For deeper debugging, enable MCP client logging (Cursor/Claude provide toggles) and inspect the JSON RPC traffic to trace tool invocations.

TODO - SP-API Implementation Checklist

Currently Implemented (12 functions)

  • [x] Authorization: GetAuthorizationCode
  • [x] Orders: GetOrders, GetOrder, GetOrderAddress, GetOrderBuyerInfo, GetOrderItems, GetOrderItemsBuyerInfo
  • [x] Sales: GetOrderMetrics
  • [x] Reports: GetReports, CreateReport, GetReport, GetReportDocument

Phase 1: Core READ Operations (High Priority)

Finances API

  • [ ] ListFinancialEventGroups - List financial event groups #4
  • [ ] ListFinancialEventsByGroupId - List financial events by group #5
  • [ ] ListFinancialEventsByOrderId - List financial events by order #6
  • [ ] ListFinancialEvents - List all financial events #7

FBA Inventory API

  • [ ] GetInventorySummaries - Get inventory summaries #8

Product Pricing API

  • [ ] GetPricing - Get pricing for products #9
  • [ ] GetCompetitivePricing - Get competitive pricing #10
  • [ ] GetListingOffers - Get listing offers
  • [ ] GetItemOffers - Get item offers
  • [ ] GetItemOffersBatch - Get item offers in batch

Product Fees API

  • [ ] GetMyFeesEstimateForSKU - Get fees estimate for SKU #11
  • [ ] GetMyFeesEstimateForASIN - Get fees estimate for ASIN #12

Phase 2: Enhanced READ Functionality (Medium Priority)

Catalog Items API

  • [ ] SearchCatalogItems - Search for catalog items #13
  • [ ] GetCatalogItem - Get details for a specific catalog item #14

Listings Items API

  • [ ] GetListingsItem - Get listing details #15

Sellers API

  • [ ] GetMarketplaceParticipations - Get marketplace participations #16

FBA Inbound API (READ-only)

  • [ ] GetInboundGuidance - Get inbound guidance for items #17
  • [ ] GetPreorderInfo - Get preorder information #18
  • [ ] GetPrepInstructions - Get prep instructions #19
  • [ ] GetTransportDetails - Get transport details #20
  • [ ] GetLabels - Get inbound shipment labels #21
  • [ ] GetBillOfLading - Get bill of lading #22
  • [ ] GetShipments - List inbound shipments #23
  • [ ] GetShipmentItemsByShipmentId - Get shipment items #24
  • [ ] GetShipmentItems - Get shipment items across shipments #25

FBA Outbound API (READ-only)

  • [ ] GetFulfillmentPreview - Get fulfillment preview #26
  • [ ] GetFulfillmentOrder - Get fulfillment order details #27
  • [ ] ListAllFulfillmentOrders - List all fulfillment orders #28
  • [ ] GetPackageTrackingDetails - Get package tracking details #29
  • [ ] ListReturnReasonCodes - List return reason codes #30
  • [ ] GetFulfillmentReturn - Get fulfillment return #31
  • [ ] GetFeatures - Get available features #32
  • [ ] GetFeatureInventory - Get feature inventory #33
  • [ ] GetFeatureSKU - Get feature SKU #34

Phase 3: Advanced READ Features (Lower Priority)

Feeds API (READ-only)

  • [ ] GetFeeds - Get feed processing reports #35
  • [ ] GetFeed - Get feed details #36
  • [ ] GetFeedDocument - Get feed document #37

Reports API (Additional READ methods)

  • [ ] GetReportSchedules - Get report schedules #38
  • [ ] GetReportSchedule - Get report schedule details #39

Messaging API (READ-only)

  • [ ] GetMessagingActionsForOrder - Get messaging actions for order #40
  • [ ] GetAttributes - Get messaging attributes #41

Notifications API (READ-only)

  • [ ] GetSubscription - Get subscription details #42
  • [ ] GetSubscriptionById - Get subscription by ID #43
  • [ ] GetDestinations - Get notification destinations #44
  • [ ] GetDestination - Get destination details #45

Merchant Fulfillment API (READ-only)

  • [ ] GetEligibleShipmentServices - Get eligible shipment services #46
  • [ ] GetShipment - Get shipment details #47
  • [ ] GetAdditionalSellerInputs - Get additional seller inputs #48

Service API (READ-only)

  • [ ] GetServiceJobs - Get service jobs #49
  • [ ] GetServiceJobByServiceJobId - Get service job details #50

Shipping API (READ-only)

  • [ ] GetShipment - Get shipment details #51
  • [ ] GetRates - Get shipping rates #52
  • [ ] GetAccount - Get account information #53
  • [ ] GetTrackingInformation - Get tracking information #54

Small and Light API (READ-only)

  • [ ] GetSmallAndLightEnrollmentBySellerSKU - Get S&L enrollment by SKU #55
  • [ ] GetSmallAndLightEligibilityBySellerSKU - Check S&L eligibility #56
  • [ ] GetSmallAndLightFeePreview - Get S&L fee preview #57

Solicitations API (READ-only)

  • [ ] GetSolicitationActionsForOrder - Get solicitation actions #58

License

TODO: No LICENSE file currently exists in this repository. Consider adding an appropriate open-source license (e.g., MIT, Apache 2.0) to clarify usage rights and distribution terms.

The referenced SP-API SDK in __reference/selling-partner-api-sdk/ is licensed separately - see __reference/selling-partner-api-sdk/LICENSE for details.

快速设置
此服务器的安装指南

安装命令 （包未发布）

git clone https://github.com/berrydev-ai/sp-api-mcp-go
手动安装： 请查看 README 获取详细的设置说明和所需的其他依赖项。

Cursor 配置 (mcp.json)

{ "mcpServers": { "berrydev-ai-sp-api-mcp-go": { "command": "git", "args": [ "clone", "https://github.com/berrydev-ai/sp-api-mcp-go" ] } } }
作者服务器
其他服务器由 berrydev-ai

Gojq MCP

MCP server by berrydev-ai

1