Quickstart Guide

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.

Create an eBay Developer Account

Visit the eBay Developer Portal
Click “Register” in the top right corner
Complete the registration process
Verify your email address

If you already have an eBay account, you can use those credentials to sign in.

Create an Application

Sign in to the Developer Portal
Navigate to “My Account” → “Application Keys”
Click “Create an Application Key”
Choose “Production” or “Sandbox” environment
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.

Configure OAuth Settings

In your application settings, scroll to “OAuth Redirect URIs”
Add the following redirect URI:
```
http://localhost:3000/callback
```
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.

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

Clone the Repository

Open your terminal and run:

git clone https://github.com/YosefHayim/ebay-mcp-server.git
cd ebay-mcp-server

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.

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.

Interactive Setup (Recommended)
Automatic Setup
Manual Configuration

The easiest way to configure your server with a beautiful CLI wizard.

npm run setup

The wizard will guide you through:

Environment Selection
- Choose between Sandbox (testing) or Production
- The wizard validates your selection
Credential Input
- Enter your eBay Client ID
- Enter your eBay Client Secret
- Set your redirect URI (default: http://localhost:3000/callback)
Validation
- Real-time validation of your credentials
- Checks for proper format and accessibility
OAuth Flow (Optional)
- Generate user tokens for full API access
- Automatically opens your browser for authorization
- Saves tokens securely in .env

The setup wizard features colorful eBay branding and clear instructions at each step.

If you prefer to edit the .env file directly first:

Create a .env file in the project root:
```
cp .env.example .env
```

Edit .env with your credentials:

EBAY_CLIENT_ID=your_client_id_here
EBAY_CLIENT_SECRET=your_client_secret_here
EBAY_ENVIRONMENT=sandbox
EBAY_REDIRECT_URI=http://localhost:3000/callback

Run automatic setup:
```
npm run auto-setup
```

This will validate your credentials and set up OAuth tokens automatically.

For advanced users who want full control:

Create .env file:
```
cp .env.example .env
```

Edit with all required variables:

# Required
EBAY_CLIENT_ID=your_client_id
EBAY_CLIENT_SECRET=your_client_secret
EBAY_ENVIRONMENT=sandbox
EBAY_REDIRECT_URI=http://localhost:3000/callback

# Optional - User Tokens (for full API access)
EBAY_USER_ACCESS_TOKEN=your_access_token
EBAY_USER_REFRESH_TOKEN=your_refresh_token
EBAY_USER_TOKEN_EXPIRY=2024-12-31T23:59:59.000Z

Without user tokens, the server will fall back to client credentials with limited rate limits (1,000 requests/day).

Step 4: Test the Server

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

Run Tests

npm test

You should see 870+ tests passing with high coverage.

If tests fail, check your .env configuration and internet connection.

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.

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:

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

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.

Restart Claude Desktop

Quit Claude Desktop completely
Reopen Claude Desktop
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.

In a chat, type:

“Show me my eBay inventory items”

Cursor will call the getInventoryItems tool and display your listings.

Try a simple authentication check:

“What’s the status of my eBay user token?”

This will call getUserTokenStatus and confirm your authentication is working.

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:

User Tokens (Recommended) - 10,000-50,000 requests/day

When to use:

You need full API access
You’re performing seller operations (listings, orders, etc.)
You want higher rate limits

Setup:

Requires OAuth 2.0 flow (handled by npm run setup)
Tokens automatically refresh
Configured via .env file

Rate Limits:

10,000-50,000 requests per day (varies by eBay account type)

The interactive setup wizard (npm run setup) handles user token generation automatically.

Client Credentials (Fallback) - 1,000 requests/day

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

Error: Invalid Client Credentials

Cause: Your Client ID or Client Secret is incorrect.Solution:

Verify your credentials in the eBay Developer Portal
Make sure you’re using credentials from the correct environment (Sandbox vs Production)
Check for typos in your .env file
Ensure there are no extra spaces or quotes around the values

Error: Redirect URI Mismatch

Cause: The redirect URI in your .env doesn’t match what’s configured in your eBay app.Solution:

Go to your eBay Developer Portal
Navigate to your application settings
Add http://localhost:3000/callback to OAuth Redirect URIs
Save and try again

MCP Client Can't Find the Server

Cause: The path in your MCP client config is incorrect.Solution:

Use an absolute path to the server (not relative)
Verify the path exists: ls /path/to/ebay-mcp-server/build/index.js
Check that you ran npm run build to create the build directory
Restart your MCP client after config changes

Rate Limit Errors

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.

Tests Failing During Installation

Cause: Missing credentials or network issues.Solution:

Configure your .env file before running tests
Check your internet connection
If using Sandbox, ensure your Sandbox credentials are valid
Try running a single test: npm test -- --run getInventoryItems.test.ts

More Help

Visit our comprehensive troubleshooting guide for more solutions

Common Questions

Do I need an active eBay seller account?

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.

Can I use this for eBay buying (not selling)?

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).

What's the difference between Sandbox and Production?

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.

How do I switch from Sandbox to Production?

Create Production credentials in the eBay Developer Portal

Update your .env file:

EBAY_ENVIRONMENT=production
EBAY_CLIENT_ID=your_production_client_id
EBAY_CLIENT_SECRET=your_production_client_secret

Run npm run setup to regenerate user tokens for production
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

Getting Started

Authentication

Core Features

Guides

MCP Integration

Advanced

Support

Step 1: Get eBay Developer Credentials

Step 2: Install the Server

Step 3: Configure Your Credentials

Step 4: Test the Server

Step 5: Connect to an MCP Client

Claude Desktop

Cursor

Other Clients

Quick Setup for Claude Desktop

Step 6: Test Your First Command

Next Steps

Create Your First Listing

Manage Orders

Run Promotions

Explore All Features

Understanding Authentication Modes

Troubleshooting

More Help

Common Questions

FAQ

What You’ve Accomplished

Learn More

Core Features

API Reference

Best Practices

Advanced Topics

Getting Started

Authentication

Core Features

Guides

MCP Integration

Advanced

Support

​Step 1: Get eBay Developer Credentials

​Step 2: Install the Server

​Step 3: Configure Your Credentials

​Step 4: Test the Server

​Step 5: Connect to an MCP Client

Claude Desktop

Cursor

Other Clients

​Quick Setup for Claude Desktop

​Step 6: Test Your First Command

​Next Steps

Create Your First Listing

Manage Orders

Run Promotions

Explore All Features

​Understanding Authentication Modes

​Troubleshooting

More Help

​Common Questions

FAQ

​What You’ve Accomplished

​Learn More

Core Features

API Reference

Best Practices

Advanced Topics

Step 1: Get eBay Developer Credentials

Step 2: Install the Server

Step 3: Configure Your Credentials

Step 4: Test the Server

Step 5: Connect to an MCP Client

Quick Setup for Claude Desktop

Step 6: Test Your First Command

Next Steps

Understanding Authentication Modes

Troubleshooting

Common Questions

What You’ve Accomplished

Learn More