Seamlessly integrate eBay's APIs into your AI assistant workflow. This MCP server enables Claude Desktop, Cursor, Cline, and other AI tools to discover and call eBay marketplace APIs directly.
Features
🔍 REST & GraphQL API Access – Search, browse, and call both REST APIs (via OpenAPI specs) and GraphQL APIs (via schema discovery) using plain language
MCP server for eBay API with OpenAPI support
2026-11-16
星标
—
工具
—
可用率
—
💬 Natural language interface – Just describe what you want; no need to memorize endpoints
🔑 Simplified setup with automatic token management – Just provide Client ID and Client Secret; the server handles OAuth token generation and refresh every ~2 hours
🗝️ Dual token mode – Application tokens for public data, User tokens for private data
⚡ MCP Prompt support – Enhanced AI assistant integration for both REST and GraphQL APIs
For Claude Code, replace -- npx -y @ebay/npm-public-api-mcp with -- node /absolute/path/to/npm-public-api-mcp/dist/index.js. All environment variables remain the same.
Step 4: Restart Your MCP Client
Restart your MCP client to load the server.
Configuration Reference
Variable
Required
Description
EBAY_CLIENT_ID
✅ Yes
eBay application Client ID
EBAY_CLIENT_SECRET
✅ Yes
eBay application Client Secret
EBAY_TOKEN_TYPE
No
"application" (default) or "user"
EBAY_REFRESH_TOKEN
Conditional
Required when EBAY_TOKEN_TYPE="user"
EBAY_REQUIRED_SCOPES
No
OAuth scopes (Application Token mode only). For multiple scopes, separate them with spaces, e.g., "https://api.ebay.com/oauth/api_scope https://api.ebay.com/oauth/api_scope/sell.inventory"
EBAY_API_ENV
No
"production" (sandbox not supported)
Tools and Prompts
This server exposes four primary tools and two MCP prompts to your AI assistant.
query_ebay_api — REST API Discovery
Searches eBay's OpenAPI specifications using a natural language prompt. Use this to explore available APIs, look up endpoint parameters, or find the right API for a task.
Find eBay APIs related to product listings
What parameters does the Browse API's getItem endpoint require?
Which API should I use to search for items by keyword?
call_ebay_api — REST API Invocation
Executes actual calls to eBay's APIs and returns live marketplace data. Typically used after query_ebay_api has identified the right endpoint.
Search for iPhone 15 listings on eBay and show me the top 5 results
Get details for eBay item ID 123456789
Show me eBay's taxonomy categories for electronics
query_ebay_graphql — GraphQL Schema Discovery
Searches eBay's GraphQL schema using a natural language prompt. Use this to explore available queries, mutations, types, and fields, or find the right operation for a task.
What fields are available on the Order type?
Which query should I use to get item details by ID?
What mutations are available for managing listings?
call_ebay_graphql — GraphQL Query Execution
Executes actual GraphQL queries against eBay's API and returns live marketplace data. Typically used after query_ebay_graphql has identified the right operation and its required fields.
Get the title, price, and seller info for listing ID 123456789
Search for iPhone 15 items and return the top 5 with prices
Fetch my active orders and their current status
You can ask in natural language — the AI selects and sequences the tools automatically.
MCP Prompts
This server registers two MCP prompts to help the client turn broad user requests into the right tool calls — one for REST APIs and one for GraphQL.
interpret_user_request — REST API Request Interpretation
Accepts the user's original request as user_input and returns guidance that helps the MCP client decide when to use query_ebay_api, when to use call_ebay_api, and how to phrase discovery queries.
Typical use cases:
Convert abstract requests into concrete eBay REST API actions
Decide whether to search API specifications first or invoke a known endpoint directly
Improve the natural-language prompt sent to query_ebay_api
Accepts the user's original request as user_input and returns guidance that helps the MCP client decide when to use query_ebay_graphql, when to use call_ebay_graphql, and how to approach schema discovery.
Typical use cases:
Convert abstract requests into specific eBay GraphQL operations
Decide whether to explore the schema first or execute a known query directly
Improve the natural-language prompt sent to query_ebay_graphql
How to Use These Prompts
Prompt
Claude Code
GitHub Copilot
REST
/ebay-api:interpret_user_request
/mcp.ebay-api.interpret_user_request
GraphQL
/ebay-api:interpret_graphql_request
/mcp.ebay-api.interpret_graphql_request
Prompt support depends on the MCP client integration. If prompts are not exposed, use the tools directly.
Usage Examples
Once connected, ask your AI assistant in natural language:
Note: You don't need to specify whether you want REST or GraphQL — the MCP explores both and automatically picks the most appropriate API.
"Find eBay APIs for listing products" — searches both REST and GraphQL APIs
"What scope permissions do I need to access my watch list?" — looks up required OAuth scopes
"What information can I query using userSavedSearches?" — explores the GraphQL schema
"Retrieve order details for IDs ORD-001 and ORD-002" — executes a real API call
OAuth Authentication Modes
Mode
Use case
Requirements
User Token
Private user data (inventory, orders, account info)
Client ID, Client Secret, Refresh Token — scopes inherited from the refresh token
✅ Use environment variables or secure vaults for production
✅ Rotate Client Secrets periodically
Token Security
Refresh tokens are long-lived — store them securely
Application tokens auto-expire after ~2 hours (the server handles refresh)
Never share tokens publicly or in screenshots
🔍 Troubleshooting
MCP Server Not Appearing:
If using Option A (npx): verify your Node.js version is 22+ and that npx is available
If using Option B (source build): verify dist/index.js exists (run npm run build) and check the absolute path in your config
Restart your MCP client
Authentication Failed (401):
Verify credentials are correct
For application token mode, check EBAY_REQUIRED_SCOPES includes necessary permissions
For user token mode, ensure refresh token is valid
Token Retrieval Failed (IDE launched from GUI):
IDEs launched from the GUI (e.g., VS Code, Cursor) may not inherit shell environment variables, causing credentials to be unresolved and token requests to fail.
Fix (quickest): Hardcode the credential values directly in the config file — just do not commit them to version control.
Fix (alternative): Launch your IDE from the terminal so it inherits the shell environment. VS Code and Cursor support this natively after a one-time CLI install from the Command Palette.
API Call Failed:
Verify that you are using the production environment
Use only REST GET requests or GraphQL Query operations; write operations are not supported
Check your eBay account has the required API access
Release Notes (v1.2.0)
If you previously used an earlier version of this MCP server, here is what has been added in this release:
GraphQL API Support – Adds schema discovery and query execution alongside existing REST API support
GraphQL MCP Prompt – Adds interpret_graphql_request alongside the existing REST API prompt