eBay API MCP Server

eBay API MCP Server

⚠️ Disclaimer

IMPORTANT: Please read this disclaimer carefully before using this software.

This is an open-source project provided "as is" without warranty of any kind, either express or implied. By using this software, you acknowledge and agree to the following:

• No Liability: The authors, contributors, and maintainers of this project accept NO responsibility or liability for any damages, losses, or issues that may arise from using this software, including but not limited to:

  • Data loss or corruption
  • Financial losses
  • Service disruptions
  • eBay account suspension or termination
  • Violations of eBay's Terms of Service or API usage policies
  • Any other direct or indirect damages

• eBay API Usage: This project is an unofficial third-party implementation and is NOT affiliated with, endorsed by, or sponsored by eBay Inc. You are solely responsible for:

  • Complying with eBay's API Terms of Use
  • Ensuring your usage stays within eBay's rate limits and policies
  • Managing your eBay Developer credentials securely
  • Understanding and complying with eBay's data handling requirements
  • Any actions performed through the API

• Use at Your Own Risk: This software is provided for educational and development purposes. Users must:

  • Test thoroughly in eBay's sandbox environment before production use
  • Understand the API calls being made on their behalf
  • Maintain backups of critical data
  • Monitor their API usage and account status

• Security: You are responsible for:

  • Keeping your API credentials secure
  • Properly configuring environment variables
  • Understanding the security implications of MCP server usage
  • Following security best practices

• No Warranty: This software is provided without any guarantees of functionality, reliability, or fitness for a particular purpose.

By using this software, you accept all risks and agree to hold harmless the authors, contributors, and maintainers from any claims, damages, or liabilities.

For official eBay API support, please refer to the eBay Developer Program.

Table of Contents

• ⚠️ Disclaimer
• Features
• Quick Start
• Configuration
• Available Tools
• Usage Examples
• Development
• Contributing
• Troubleshooting
• Resources
• License

Features

• 230+ eBay API Tools - Comprehensive coverage of eBay Sell APIs across inventory, orders, marketing, analytics, and more
• OAuth 2.0 Support - Full user token management with automatic refresh
• Type Safety - Built with TypeScript, Zod validation, and OpenAPI-generated types
• MCP Integration - STDIO transport for direct integration with AI assistants
• Smart Authentication - Automatic fallback from user tokens (10k-50k req/day) to client credentials (1k req/day)
• Well Tested - 870+ tests with 99%+ function coverage

Quick Start

1. Get eBay Credentials

1. Create a free eBay Developer Account
2. Generate application keys in the Developer Portal
3. Save your Client ID and Client Secret

2. Install

Option A: Install from npm (Recommended)

npm install -g ebay-mcp

Option B: Install from source

git clone https://github.com/YosefHayim/ebay-mcp.git
cd ebay-mcp
npm install
npm run build

3. Configure

Run the interactive setup wizard:

npm run setup

Or manually configure:

cp .env.example .env
# Edit .env with your credentials
npm run auto-setup

4. Configure MCP Client

Add this server to your MCP client configuration:

Claude Desktop:

Edit your Claude Desktop config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Add the server configuration:

{
  "mcpServers": {
    "ebay": {
      "command": "npx",
      "args": ["-y", "ebay-mcp"],
      "env": {
        "EBAY_CLIENT_ID": "your_client_id",
        "EBAY_CLIENT_SECRET": "your_client_secret",
        "EBAY_ENVIRONMENT": "sandbox",
        "EBAY_REDIRECT_URI": "your_runame"
      }
    }
  }
}

Alternative: Use locally installed version

If you installed from source:

{
  "mcpServers": {
    "ebay": {
      "command": "node",
      "args": ["/absolute/path/to/ebay-mcp/build/index.js"],
      "env": {
        "EBAY_CLIENT_ID": "your_client_id",
        "EBAY_CLIENT_SECRET": "your_client_secret",
        "EBAY_ENVIRONMENT": "sandbox"
      }
    }
  }
}

5. Use

Restart your MCP client (Claude Desktop, etc.) and start using eBay tools through your AI assistant.

Configuration

Environment Variables

Create a .env file with your eBay credentials:

EBAY_CLIENT_ID=your_client_id
EBAY_CLIENT_SECRET=your_client_secret
EBAY_ENVIRONMENT=sandbox  # or "production"
EBAY_REDIRECT_URI=your_runame

# Optional: For higher rate limits (10k-50k req/day)
EBAY_USER_REFRESH_TOKEN=your_refresh_token

OAuth Authentication

Client Credentials (Automatic):

• Default authentication method
• 1,000 requests/day
• No setup required beyond client ID and secret

User Tokens (Recommended for Production):

• 10,000-50,000 requests/day
• Use ebay_get_oauth_url tool to generate authorization URL
• Add EBAY_USER_REFRESH_TOKEN to .env after OAuth flow
• Tokens refresh automatically

For detailed OAuth setup, see the OAuth documentation.

MCP Client Compatibility

This server is compatible with any MCP client that supports STDIO transport:

Tested and Supported:

• ✅ Claude Desktop (macOS, Windows, Linux) - Full support
• ✅ MCP Inspector - For development and testing
• ✅ Custom MCP Clients - Via STDIO or HTTP transport

Configuration Requirements:

• MCP Protocol version: 1.0+
• Transport: STDIO (default) or HTTP
• Node.js runtime: 18.0.0 or higher

Other MCP Clients:

While not specifically tested, the server should work with any MCP-compliant client including:

• Continue.dev
• Other editors with MCP support
• Custom implementations

If you successfully use this server with another MCP client, please let us know by opening a discussion!

Rate Limiting

Understanding eBay API rate limits is crucial for production use:

Client Credentials (Default):

• Daily Limit: 1,000 requests per day
• Best For: Development, testing, low-volume operations
• Setup: Automatic with just Client ID and Secret

User Token (Recommended):

• Daily Limit: 10,000-50,000 requests per day (varies by account type)
• Best For: Production, high-volume operations
• Setup: Requires OAuth flow (use ebay_get_oauth_url tool)

Rate Limit Tiers by Account Type:

• Individual Developer: 10,000 requests/day
• Commercial Developer: 25,000 requests/day
• Enterprise: 50,000+ requests/day (custom limits)

Rate Limit Best Practices:

1. Use user tokens for production workloads
2. Implement exponential backoff on rate limit errors
3. Cache responses when possible
4. Monitor your usage in the eBay Developer Portal
5. Batch operations when the API supports it
6. Consider upgrading your developer account tier for higher limits

Handling Rate Limits:

When you hit a rate limit, the API returns a 429 status code. The server will:

• Automatically retry with exponential backoff
• Inform you of rate limit errors
• Suggest upgrading to user token authentication

Check Current Usage:

Monitor your API usage in the eBay Developer Portal.

Available Tools

The server provides 230+ tools organized into the following categories:

• Account Management - Policies, programs, subscriptions, sales tax
• Inventory Management - Items, offers, locations, bulk operations
• Order Fulfillment - Orders, shipping, refunds, disputes
• Marketing & Promotions - Campaigns, ads, promotions, bidding
• Analytics - Traffic reports, seller standards, metrics
• Communication - Buyer-seller messaging, negotiations
• Metadata & Taxonomy - Categories, item aspects, policies
• Token Management - OAuth URL generation, token management

Example Tools:

• ebay_get_inventory_items - List all inventory items
• ebay_get_orders - Retrieve seller orders
• ebay_create_offer - Create new listing offer
• ebay_get_campaigns - Get marketing campaigns
• ebay_get_oauth_url - Generate OAuth authorization URL

For the complete tool list, see src/tools/definitions/.

Usage Examples

Here are some common tasks you can accomplish with the eBay MCP server:

Setting Up OAuth for Higher Rate Limits

User: "Can you help me set up OAuth authentication for my eBay account?"

Assistant: Uses ebay_get_oauth_url tool to generate an authorization URL. You visit the URL, grant permissions, and the assistant helps you configure the refresh token in your .env file.

Result: Access to 10,000-50,000 API requests per day instead of 1,000.

Managing Inventory

User: "Show me all my active listings on eBay"

Assistant: Uses ebay_get_inventory_items to retrieve all inventory items.

Result: Displays a formatted list of all your products with SKUs, quantities, and status.

Processing Orders

User: "Get all unfulfilled orders from the last 7 days"

Assistant: Uses ebay_get_orders with date filters and fulfillment status parameters.

Result: Returns a list of pending orders ready for shipment processing.

Creating Marketing Campaigns

User: "Create a promoted listing campaign for my electronics category"

Assistant: Uses ebay_create_campaign and related marketing tools to set up ad campaigns.

Result: New campaign created with specified budget and target items.

Bulk Operations

User: "Update prices for all items in category 'Vintage Watches' with a 10% discount"

Assistant: Combines ebay_get_inventory_items, filters by category, and uses ebay_update_offer to apply bulk pricing changes.

Result: All matching items updated with new pricing.

Development

Prerequisites

• Node.js >= 18.0.0
• npm or pnpm
• eBay Developer Account

Setup

# Fork and clone the repository
git clone https://github.com/YOUR_USERNAME/ebay-mcp.git
cd ebay-mcp

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env with your credentials

# Build and test
npm run build
npm test

Development Commands

npm run dev              # Run STDIO server
npm run dev:http         # Run HTTP server
npm run test             # Run tests
npm run test:watch       # Run tests in watch mode
npm run typecheck        # Type-check code
npm run lint             # Lint code
npm run format           # Format code

Docker Support

Run the server in a containerized environment:

# Build the Docker image
npm run docker:build

# Start the container
npm run docker:up

# View logs
npm run docker:logs

# Stop the container
npm run docker:down

# Restart the container
npm run docker:restart

Docker Compose Configuration:

The server can be run with Docker Compose for easy deployment:

docker-compose up -d

Environment variables should be configured in .env file before running Docker commands. The container will automatically use your .env configuration.

Use Cases for Docker:

• Production deployments
• Consistent development environments
• CI/CD pipelines
• Isolated testing environments

HTTP Server Mode

In addition to the default STDIO transport for MCP clients, the server can run in HTTP mode for testing and debugging:

# Development
npm run dev:http

# Production
npm run start:http

HTTP Mode Features:

• RESTful API endpoints for all tools
• Interactive API documentation
• Useful for testing tools without an MCP client
• CORS support for web applications
• Helmet security headers

When to Use HTTP Mode:

• Testing individual tools during development
• Building custom integrations
• Debugging API responses
• Creating web-based interfaces

Note: STDIO mode (default) is recommended for MCP client integration (Claude Desktop, etc.). HTTP mode is primarily for development and custom integrations.

Project Structure

ebay-mcp/
├── src/
│   ├── index.ts           # MCP server entry point
│   ├── api/               # eBay API implementations
│   ├── auth/              # OAuth & token management
│   ├── tools/             # MCP tool definitions
│   ├── types/             # TypeScript types
│   └── utils/             # Validation schemas
├── tests/                 # Test suite
├── docs/                  # Documentation
└── build/                 # Compiled output

For detailed contribution guidelines, see CONTRIBUTING.md.

Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes and add tests
4. Run quality checks: npm run check && npm test
5. Commit using Conventional Commits
6. Push to your fork and open a Pull Request

Before submitting:

• Ensure all tests pass
• Follow TypeScript best practices
• Update documentation as needed
• Maintain test coverage

See CONTRIBUTING.md for detailed guidelines.

Troubleshooting

Common Issues

Server Not Appearing in Claude Desktop

Problem: The eBay MCP server doesn't show up in your MCP client.

Solutions:

1. Verify the config file path is correct for your OS
2. Check JSON syntax is valid (use a JSON validator)
3. Ensure environment variables are properly set
4. Restart Claude Desktop completely
5. Check Claude Desktop logs for error messages

Authentication Errors

Problem: "Invalid credentials" or "Authentication failed" errors.

Solutions:

1. Verify your EBAY_CLIENT_ID and EBAY_CLIENT_SECRET are correct
2. Ensure you're using the right environment (sandbox vs production)
3. Check if your app keys are active in the eBay Developer Portal
4. For user tokens, verify your EBAY_USER_REFRESH_TOKEN is valid
5. Run npm run diagnose to check your configuration

Rate Limit Errors

Problem: "Rate limit exceeded" errors.

Solutions:

1. Upgrade to user token authentication (10k-50k requests/day)
2. Implement request throttling in your usage
3. Check your current rate limit in the Developer Portal
4. Consider upgrading your eBay Developer account tier

Tools Not Working Correctly

Problem: Tools return unexpected errors or empty results.

Solutions:

1. Verify you're using the correct environment (sandbox vs production)
2. Ensure you have proper permissions/scopes for the operation
3. Check eBay API status: https://developer.ebay.com/support/api-status
4. Run npm run diagnose:export to generate a diagnostic report
5. Review the eBay API documentation for endpoint requirements

Diagnostic Tools

Run diagnostics to troubleshoot configuration issues:

# Interactive diagnostics
npm run diagnose

# Export diagnostic report
npm run diagnose:export

The diagnostic tool checks:

• Environment variable configuration
• eBay API connectivity
• Authentication status
• Token validity
• Available scopes and permissions

Getting Help

If you're still experiencing issues:

1. Check existing GitHub Issues
2. Review GitHub Discussions
3. Create a new issue with:
   • Your diagnostic report (npm run diagnose:export)
   • Steps to reproduce the problem
   • Error messages or logs
   • Your environment (OS, Node version, MCP client)

Resources

Documentation

• eBay Developer Portal - API documentation and credentials
• eBay API License Agreement - Terms of use and compliance requirements
• eBay Data Handling Requirements - Important data protection and privacy guidelines
• eBay API Status - Real-time API health and status
• MCP Documentation - Model Context Protocol specification
• OAuth Setup Guide - Detailed authentication configuration
• Contributing Guidelines - How to contribute to this project
• Code of Conduct - Community guidelines and expectations
• Changelog - Version history and release notes
• Security Policy - Vulnerability reporting guidelines

Support

• GitHub Discussions - Community Q&A and general discussions
• Issue Tracker - Bug reports and feature requests
• Bug Report Template - Detailed bug reporting guide

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• eBay Developers Program for API access
• Model Context Protocol for the MCP specification
• All contributors who have helped improve this project