Skip to main content
This guide covers all configuration options for the eBay MCP Server.

​
Prerequisites

Before configuring, you need:
  • eBay Developer account (Sign up here)
  • An eBay application with API credentials
  • The server installed on your system

Need credentials?

Follow Step 1 of the Quickstart Guide to get your eBay Developer credentials

​
Configuration Methods

The eBay MCP Server supports three configuration methods:

Interactive Setup

Recommended for beginnersGuided wizard with validation

Automatic Setup

For quick configurationEdit .env then run setup

Manual Setup

For advanced usersComplete control over all settings
The easiest way to configure your server: 
npm run setup

​
What the Wizard Does

1

Environment Selection

Choose your eBay environment:
  • Sandbox: For testing (recommended initially)
  • Production: For live operations
Always start with Sandbox for safe testing
2

Credential Input

Enter your eBay credentials:
  • Client ID (from eBay Developer Portal)
  • Client Secret (from eBay Developer Portal)
  • Redirect URI (default: http://localhost:3000/callback)
The wizard validates each input in real-time.
3

OAuth Flow (Optional)

Generate user access tokens for full API access:
  1. Wizard generates an authorization URL
  2. Opens your browser automatically
  3. You authorize the application on eBay
  4. Wizard captures the OAuth code
  5. Exchanges code for access and refresh tokens
  6. Saves tokens securely in .env
User tokens provide 10,000-50,000 requests/day vs 1,000 for client credentials
4

Confirmation

The wizard confirms successful configuration and shows:
  • Environment (Sandbox/Production)
  • Authentication method (User tokens/Client credentials)
  • Expected rate limits

​
Method 2: Automatic Setup

For users who prefer to edit configuration files:
1

Create .env File

cp .env.example .env
2

Edit Configuration

Open .env in your editor:
# Required credentials
EBAY_CLIENT_ID=YourAppId-12345
EBAY_CLIENT_SECRET=YourCertId-67890
EBAY_ENVIRONMENT=sandbox
EBAY_REDIRECT_URI=http://localhost:3000/callback
Replace the example values with your actual credentials from the eBay Developer Portal
3

Run Automatic Setup

npm run auto-setup
This command:
  • Validates your credentials
  • Initiates OAuth flow for user tokens
  • Tests API connectivity
  • Confirms successful configuration

​
Method 3: Manual Configuration

For complete control over all settings:
1

Create .env File

cp .env.example .env
2

Configure All Variables

Edit .env with all required and optional variables:
# ============================================
# REQUIRED: eBay Developer Credentials
# ============================================
EBAY_CLIENT_ID=YourAppId-12345
EBAY_CLIENT_SECRET=YourCertId-67890

# Environment: sandbox or production
EBAY_ENVIRONMENT=sandbox

# OAuth redirect URI (must match eBay app settings)
EBAY_REDIRECT_URI=http://localhost:3000/callback

# ============================================
# OPTIONAL: User Access Tokens
# ============================================
# User access token (for full API access)
EBAY_USER_ACCESS_TOKEN=v^1.1#i^1#...

# User refresh token (for automatic token renewal)
EBAY_USER_REFRESH_TOKEN=v^1.1#i^1#...

# Token expiry timestamp (ISO 8601 format)
EBAY_USER_TOKEN_EXPIRY=2024-12-31T23:59:59.000Z

# ============================================
# OPTIONAL: Server Configuration
# ============================================
# MCP transport (default: stdio)
MCP_TRANSPORT=stdio

# Log level: error, warn, info, debug
LOG_LEVEL=info

# Enable request logging
LOG_REQUESTS=false
3

Validate Configuration

Test your configuration:
npm run validate-config
This checks:
  • All required variables are set
  • Credentials are valid format
  • API connectivity works
  • Tokens are valid (if provided)

​
Environment Variables Reference

​
Required Variables

VariableDescriptionExample
EBAY_CLIENT_IDYour eBay App IDYourAppName-YourApp-SBX-1234abcd-567890ab
EBAY_CLIENT_SECRETYour eBay Cert IDSBX-1234abcd-5678-90ab-cdef-1234
EBAY_ENVIRONMENTAPI environmentsandbox or production
EBAY_REDIRECT_URIOAuth redirect URIhttp://localhost:3000/callback

​
Optional Variables (User Tokens)

VariableDescriptionFormat
EBAY_USER_ACCESS_TOKENUser access tokenv^1.1#i^1#... (long string)
EBAY_USER_REFRESH_TOKENUser refresh tokenv^1.1#i^1#... (long string)
EBAY_USER_TOKEN_EXPIRYToken expiry time2024-12-31T23:59:59.000Z

​
Optional Variables (Server Settings)

VariableDescriptionDefaultOptions
MCP_TRANSPORTMCP transport typestdiostdio, sse
LOG_LEVELLogging verbosityinfoerror, warn, info, debug
LOG_REQUESTSLog all API requestsfalsetrue, false

​
Authentication Modes

The server supports two authentication modes:
  • Overview
  • Setup
  • Rate Limits
Best for:
  • Full API access (all 230+ tools)
  • High rate limits (10,000-50,000 requests/day)
  • Production usage
  • Automated seller operations
How it works:
  • Requires OAuth 2.0 authorization
  • User authorizes your application
  • Tokens automatically refresh
  • Secure token storage in .env

​
Client Credentials (Fallback)

  • Overview
  • Setup
  • Limitations
Best for:
  • Testing basic functionality
  • App-level operations only
  • Development/testing
  • No OAuth flow needed
How it works:
  • Automatic authentication
  • Only requires Client ID and Secret
  • Used when no user tokens are present
  • Limited API access

​
Switching Environments

​
Sandbox to Production

1

Create Production App

  1. Visit eBay Developer Portal
  2. Create a new application
  3. Select Production environment
  4. Note your production credentials
2

Update Configuration

Edit .env:
EBAY_ENVIRONMENT=production
EBAY_CLIENT_ID=YourProdAppId
EBAY_CLIENT_SECRET=YourProdCertId
Remove sandbox tokens if present - they won’t work in production
3

Generate Production Tokens

npm run setup
Follow the OAuth flow to generate production user tokens.
4

Verify Production Setup

npm run validate-config
Ensure production credentials are working.
Production operations affect real listings and transactions. Always test thoroughly in Sandbox first.

​
Security Best Practices

Never commit .env to version control:
# Verify .env is in .gitignore
cat .gitignore | grep .env
Set proper file permissions:
chmod 600 .env
For production deployments:
  • Use environment variables (not .env files)
  • Use secret management services (AWS Secrets Manager, Azure Key Vault, etc.)
For production:
  1. Generate new credentials in eBay Developer Portal
  2. Update your .env file
  3. Regenerate user tokens: npm run setup
  4. Delete old credentials from eBay portal
Recommended schedule:
  • Rotate every 90 days minimum
  • Immediately if credentials are compromised
Best practice:
  • Separate Sandbox credentials
  • Separate Production credentials
  • Never use production credentials for testing
Organization:
# Use separate .env files
.env.sandbox
.env.production

# Load appropriate file:
cp .env.sandbox .env  # for testing
cp .env.production .env  # for production
Track your usage to prevent hitting limits:
# Enable request logging
LOG_REQUESTS=true
LOG_LEVEL=debug
Use eBay tools to check rate limits:
  • Monitor via eBay Developer Portal
  • Check current usage with getRateLimitStatus tool
  • Set up alerts before hitting limits

​
Troubleshooting

Check these common issues:
  1. Typos in Client ID or Secret
  2. Extra spaces or quotes in .env values
  3. Wrong environment (Sandbox credentials in Production mode)
  4. Expired user tokens
Solution:
# Re-run setup wizard
npm run setup

# Or validate manually
npm run validate-config
Common causes:
  1. Redirect URI mismatch
  2. Application not configured for OAuth
  3. Browser blocking popups
Solutions:
  1. Verify redirect URI in eBay Developer Portal matches .env
  2. Add http://localhost:3000/callback to your app’s OAuth settings
  3. Allow popups from the setup wizard
Possible issues:
  1. System clock is incorrect
  2. Token expiry timestamp is wrong format
Solutions:
# Check system time
date

# Regenerate tokens
npm run setup

​
Next Steps

Connect MCP Client

Configure your MCP client to use the server

Authentication Guide

Deep dive into authentication options

First Listing

Create your first eBay listing

Best Practices

Tips for optimal configuration