Skip to main content
This guide will walk you through setting up the eBay MCP Server from scratch. By the end, you’ll have a fully functional MCP server connected to your AI assistant.
Time to complete: Approximately 10 minutesPrerequisites:
  • Node.js 18 or higher installed
  • Git installed
  • An eBay Developer account (we’ll help you create one)

​
Step 1: Get eBay Developer Credentials

Before installing the server, you need eBay Developer credentials.
1

Create an eBay Developer Account

  1. Visit the eBay Developer Portal
  2. Click “Register” in the top right corner
  3. Complete the registration process
  4. Verify your email address
If you already have an eBay account, you can use those credentials to sign in.
2

Create an Application

  1. Sign in to the Developer Portal
  2. Navigate to “My Account” → “Application Keys”
  3. Click “Create an Application Key”
  4. Choose “Production” or “Sandbox” environment
  5. Fill in your application details:
    • Application Title: Choose a descriptive name (e.g., “My eBay MCP Server”)
    • Application Type: Select “Public Application”
Start with the Sandbox environment for testing. Switch to Production when you’re ready to go live.
3

Configure OAuth Settings

  1. In your application settings, scroll to “OAuth Redirect URIs”
  2. Add the following redirect URI: 
    http://localhost:3000/callback
  3. Click “Save” and note your credentials:
    • Client ID (App ID)
    • Client Secret (Cert ID)
Keep these credentials secure - you’ll need them in Step 3.
4

Grant Application Scopes

Ensure your application has the following scopes enabled:
  • https://api.ebay.com/oauth/api_scope/sell.inventory
  • https://api.ebay.com/oauth/api_scope/sell.marketing
  • https://api.ebay.com/oauth/api_scope/sell.fulfillment
  • https://api.ebay.com/oauth/api_scope/sell.analytics.readonly
  • https://api.ebay.com/oauth/api_scope/sell.account
  • https://api.ebay.com/oauth/api_scope/sell.account.readonly
Most of these scopes are enabled by default. Verify them in your application settings.

​
Step 2: Install the Server

1

Clone the Repository

Open your terminal and run:
git clone https://github.com/YosefHayim/ebay-mcp-server.git
cd ebay-mcp-server
2

Install Dependencies

npm install
This will install all required dependencies including the MCP SDK and eBay Sell APIs client libraries.
Installation typically takes 30-60 seconds depending on your internet connection.
3

Verify Installation

Check that everything installed correctly:
npm run version
You should see version information for the eBay MCP Server.

​
Step 3: Configure Your Credentials

The eBay MCP Server offers three configuration methods. Choose the one that works best for you.

​
Step 4: Test the Server

Before connecting to an MCP client, verify the server works:
1

Run Tests

npm test
You should see 870+ tests passing with high coverage.
If tests fail, check your .env configuration and internet connection.
2

Start the Server

npm start
The server will start in STDIO mode, ready for MCP client connections.
You should see initialization logs confirming the server is ready.
3

Verify Authentication

The server automatically validates your credentials on startup. Check the logs for:
  • ✅ Client credentials validated
  • ✅ User tokens loaded (if configured)
  • ✅ 230+ tools registered

​
Step 5: Connect to an MCP Client

Choose your preferred AI assistant and follow the integration guide:

Claude Desktop

Official Anthropic desktop app with native MCP support

Cursor

AI-first code editor with MCP integration

Other Clients

Cline, Gemini, ChatGPT, and more

​
Quick Setup for Claude Desktop

The most popular option - here’s a quick guide:
1

Locate Claude Desktop Config

The config file location depends on your OS:macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
%APPDATA%\Claude\claude_desktop_config.json
Linux:
~/.config/Claude/claude_desktop_config.json
2

Add eBay MCP Server

Edit the config file and add:
{
  "mcpServers": {
    "ebay": {
      "command": "node",
      "args": ["/absolute/path/to/ebay-mcp-server/build/index.js"],
      "env": {
        "EBAY_CLIENT_ID": "your_client_id",
        "EBAY_CLIENT_SECRET": "your_client_secret",
        "EBAY_ENVIRONMENT": "sandbox"
      }
    }
  }
}
Replace /absolute/path/to/ebay-mcp-server with the actual path where you cloned the repository.
3

Restart Claude Desktop

  1. Quit Claude Desktop completely
  2. Reopen Claude Desktop
  3. Look for the 🔨 tools icon - you should now see eBay tools available!

​
Step 6: Test Your First Command

Let’s verify everything works by testing a simple eBay Sell APIs call:
  • In Claude Desktop
  • In Cursor
  • Testing Authentication
Try asking Claude:
“Can you list my eBay fulfillment policies?”
Claude will use the getFulfillmentPolicies tool and show you your configured policies.
Success! You now have a fully functional eBay MCP Server.

​
Next Steps

Now that your server is running, explore its capabilities:

Create Your First Listing

Step-by-step guide to creating an eBay listing via MCP

Manage Orders

Learn how to fulfill orders and handle returns

Run Promotions

Set up marketing campaigns and promoted listings

Explore All Features

Discover all 230+ tools and what they can do

​
Understanding Authentication Modes

The server supports two authentication modes:
When to use:
  • You only need app-level operations
  • You’re testing basic functionality
  • You want zero-configuration authentication
Setup:
  • Automatically used if no user tokens are present
  • Only requires Client ID and Secret
  • No OAuth flow needed
Rate Limits:
  • 1,000 requests per day
Limitations:
  • Cannot access user-specific data
  • Limited to public/app-level operations
For most use cases, you’ll want user tokens for full functionality.

​
Troubleshooting

Cause: Your Client ID or Client Secret is incorrect.Solution:
  1. Verify your credentials in the eBay Developer Portal
  2. Make sure you’re using credentials from the correct environment (Sandbox vs Production)
  3. Check for typos in your .env file
  4. Ensure there are no extra spaces or quotes around the values
Cause: The redirect URI in your .env doesn’t match what’s configured in your eBay app.Solution:
  1. Go to your eBay Developer Portal
  2. Navigate to your application settings
  3. Add http://localhost:3000/callback to OAuth Redirect URIs
  4. Save and try again
Cause: The path in your MCP client config is incorrect.Solution:
  1. Use an absolute path to the server (not relative)
  2. Verify the path exists: ls /path/to/ebay-mcp-server/build/index.js
  3. Check that you ran npm run build to create the build directory
  4. Restart your MCP client after config changes
Cause: You’ve exceeded your daily API request limit.Solution:
  • With client credentials: Upgrade to user tokens for higher limits
  • With user tokens: Wait 24 hours or upgrade your eBay seller account
  • Check your usage: Use the getRateLimitStatus tool (if available)
User tokens provide 10-50x more requests than client credentials.
Cause: Missing credentials or network issues.Solution:
  1. Configure your .env file before running tests
  2. Check your internet connection
  3. If using Sandbox, ensure your Sandbox credentials are valid
  4. Try running a single test: npm test -- --run getInventoryItems.test.ts

More Help

Visit our comprehensive troubleshooting guide for more solutions

​
Common Questions

For Sandbox: No, you can test with just a developer account.For Production: Yes, you need an active eBay seller account to use production APIs.The Sandbox environment is perfect for development and testing without any seller requirements.
No, this MCP server focuses on eBay’s Sell APIs. It’s designed for sellers to manage:
  • Inventory and listings
  • Orders and fulfillment
  • Marketing campaigns
  • Business analytics
For buying operations, you’d need eBay’s Buy APIs (not currently supported).
Sandbox:
  • Test environment with fake data
  • Free to use
  • No real transactions
  • Perfect for development
Production:
  • Real eBay marketplace
  • Real transactions and fees
  • Requires active seller account
  • Use after thorough testing in Sandbox
Always develop and test in Sandbox before switching to Production.
  1. Create Production credentials in the eBay Developer Portal
  2. Update your .env file: 
    EBAY_ENVIRONMENT=production
EBAY_CLIENT_ID=your_production_client_id
EBAY_CLIENT_SECRET=your_production_client_secret
  3. Run npm run setup to regenerate user tokens for production
  4. Restart your MCP server
Production operations affect real listings and transactions. Test thoroughly in Sandbox first.

FAQ

See all frequently asked questions

​
What You’ve Accomplished

  • ✅ Created an eBay Developer account and application
  • ✅ Installed and configured the eBay MCP Server
  • ✅ Set up authentication (user tokens or client credentials)
  • ✅ Connected the server to your MCP client
  • ✅ Tested your first eBay Sell APIs call
You’re now ready to automate your eBay selling operations with AI!

​
Learn More

Core Features

Explore all capabilities in detail

API Reference

Complete documentation of all 230+ tools

Best Practices

Tips for optimal usage and performance

Advanced Topics

Deep dive into architecture and internals