Frequently Asked Questions

Find quick answers to the most frequently asked questions about installing, configuring, and using the eBay MCP Server.

Don’t see your question? Check the Troubleshooting Guide or ask on GitHub Discussions.

Getting Started

What is the eBay MCP Server?

The eBay MCP Server is a Model Context Protocol (MCP) implementation that provides AI assistants with comprehensive access to eBay’s Sell APIs.Key features:

230+ tools covering eBay selling operations
99.1% API coverage (110/111 eBay Sell APIs endpoints)
Full authentication support with OAuth 2.0
Compatible with Claude Desktop, Cursor, and other MCP clients
Well-tested with 870+ tests and 99%+ function coverage

It allows AI assistants like Claude to help you manage your eBay business through natural language conversations.

Learn More

Read the full introduction

Do I need programming experience to use this?

No, programming experience is not required for basic usage.For basic setup and use:

Follow the Quickstart Guide step-by-step
Use the interactive setup wizard: npm run setup
Interact through your MCP client (Claude Desktop, Cursor, etc.)
No coding needed - just configure and use through AI conversations

Programming is helpful for:

Advanced customization
Contributing to the project
Debugging complex issues
Integrating with custom workflows

The setup wizard handles most technical details automatically.

Do I need an active eBay seller account?

It depends on your environment:For Sandbox (testing):

❌ No seller account required
Only need an eBay Developer account (free)
Perfect for learning and development
Create test listings without real transactions

For Production (live operations):

✅ Yes, active seller account required
Must be registered as an eBay seller
Account must be in good standing
Used for real listings and transactions

We recommend starting with Sandbox to learn the system before using Production.

How much does this cost?

The eBay MCP Server itself is completely free:

✅ Open source under Apache 2.0 license
✅ No subscription fees
✅ No usage limits from the MCP server
✅ Free to use for personal and commercial projects

However, you may incur costs from:

eBay fees (when using Production):
- Standard eBay selling fees apply
- Final value fees on sold items
- Optional listing upgrades
MCP client costs (varies by client):
- Claude Desktop Pro: $20/month (optional)
- Cursor: Free or $20/month for Pro features
- Other clients: Check individual pricing
eBay Sell APIs rate limits:
- Sandbox: Unlimited requests (free)
- Production with client credentials: 1,000 requests/day (free)
- Production with user tokens: 10,000-50,000 requests/day (free with eBay account)

The server itself will never charge you anything. It’s completely free and open source.

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

No, this server focuses exclusively on eBay’s Sell APIs.What the server DOES:

✅ Create and manage listings
✅ Fulfill orders
✅ Run marketing campaigns
✅ Analyze business metrics
✅ Manage seller account settings

What the server does NOT do:

❌ Browse eBay as a buyer
❌ Make purchases
❌ Search for products to buy
❌ Manage buyer accounts

Why?

Built specifically for sellers and businesses
Uses eBay’s Sell APIs family (not Buy APIs)
Designed for seller operations and automation

For buying operations, you would need a different integration using eBay’s Buy APIs.

Which AI assistants work with this server?

The eBay MCP Server works with any MCP-compatible client:Fully Tested:

✅ Claude Desktop - Official Anthropic app with native MCP support
✅ Cursor - AI-first code editor
✅ Cline (formerly Claude Dev) - VS Code extension

Also Compatible:

Continue (VS Code extension)
Zed editor (experimental MCP support)
Any custom MCP client following the specification

Not Currently Supported:

ChatGPT (doesn’t support MCP)
Google Gemini web interface (doesn’t support MCP)
Copilot (uses different protocol)

Integration Guides

See setup guides for each client

Installation & Setup

What are the system requirements?

Minimum requirements:Software:

Node.js: Version 18.0.0 or higher
npm: Version 8.0.0 or higher (comes with Node.js)
Git: Latest version recommended
Operating System: macOS, Linux, or Windows

Hardware:

Disk Space: ~500 MB for installation
RAM: 512 MB minimum, 1 GB recommended
CPU: Any modern processor

Network:

Internet connection for eBay Sell APIs access
Ability to reach api.ebay.com

Verify your system:

node --version  # Should show v18.x.x or higher
npm --version   # Should show v8.x.x or higher
git --version   # Should show git version 2.x.x

Install the Node.js LTS (Long Term Support) version from nodejs.org

How long does installation take?

Typical installation timeline:

Get eBay credentials: 5-10 minutes
- Create developer account
- Set up application
- Note Client ID and Secret
Install server: 2-3 minutes
- Clone repository: ~30 seconds
- Install dependencies: ~1-2 minutes
- Build project: ~30 seconds
Configure credentials: 2-5 minutes
- Run setup wizard: ~2-3 minutes
- Complete OAuth flow: ~1-2 minutes
Connect MCP client: 1-2 minutes
- Edit config file
- Restart client

Total time: 10-20 minutes for complete setup

Following the Quickstart Guide ensures the fastest setup experience.

Where do I get eBay Developer credentials?

Step-by-step process:

Create eBay Developer account:
- Visit developer.ebay.com
- Click “Register” in top right
- Complete registration (free)
Create an Application:
- Sign in to Developer Portal
- Go to My Account → Application Keys
- Click Create an Application Key
- Choose Sandbox (for testing) or Production
Get your credentials:
- Client ID (also called App ID)
- Client Secret (also called Cert ID)
- Copy these - you’ll need them for setup
Configure OAuth:
- Add redirect URI: http://localhost:3000/callback
- Save your application

Credentials are free and generated instantly.

Detailed Guide

See full credential setup guide

Should I use Sandbox or Production?

Use Sandbox first, then Production later.Sandbox (Recommended for starting):

✅ Safe testing environment
✅ No real transactions
✅ Free to use
✅ No seller account needed
✅ Perfect for learning
❌ Fake data only
❌ Doesn’t affect real eBay

Production (For live operations):

✅ Real eBay marketplace
✅ Actual listings and sales
✅ Real customer orders
⚠️ Real transactions and fees
⚠️ Requires active seller account
⚠️ Mistakes affect real business

Recommended workflow:

Start with Sandbox
Learn the tools and workflows
Test your processes thoroughly
Switch to Production when confident

Always test new operations in Sandbox first before using them in Production.

How do I switch from Sandbox to Production?

Complete process:

Create Production Application

Visit eBay Developer Portal
Create a new application key
Select Production environment
Copy your Production Client ID and Secret

Update Environment Variables

Edit your .env file:

EBAY_ENVIRONMENT=production
EBAY_CLIENT_ID=YourProdClientId
EBAY_CLIENT_SECRET=YourProdClientSecret

Important: Remove any Sandbox tokens:

Delete EBAY_USER_ACCESS_TOKEN
Delete EBAY_USER_REFRESH_TOKEN
Delete EBAY_USER_TOKEN_EXPIRY

Generate Production Tokens

npm run setup

Complete the OAuth flow with your Production credentials.

Verify Configuration

npm run validate-config

Ensure Production credentials are working.

Restart MCP Server

Restart your MCP client to load the new credentials.

Sandbox and Production credentials are completely separate. You can’t mix them.

Authentication & Security

What's the difference between User Tokens and Client Credentials?

Two authentication modes with different capabilities:User Tokens (OAuth 2.0) - Recommended:

✅ Full API access - all 230+ tools available
✅ High rate limits - 10,000-50,000 requests/day
✅ User-specific operations - manage your listings, orders, etc.
✅ Automatic refresh - tokens renew automatically
⚠️ Requires OAuth flow (one-time setup)

Client Credentials - Fallback:

✅ Simple setup - just Client ID and Secret
✅ No OAuth needed - automatic authentication
❌ Limited rate limits - only 1,000 requests/day
❌ Restricted access - can’t access user-specific data
❌ Fewer tools available

Comparison:

Feature	User Tokens	Client Credentials
Rate Limit	10K-50K/day	1,000/day
Setup Complexity	OAuth flow	Simple
API Access	Full (230+ tools)	Limited
Best For	Production use	Testing only

The setup wizard (npm run setup) configures user tokens automatically.

How do I know if my tokens are working?

Several ways to verify:1. Run configuration validator:

npm run validate-config

This checks:

Credentials are valid
Tokens are not expired
API connectivity works

2. Check server startup logs:

npm start

Look for:

✅ “Client credentials validated”
✅ “User tokens loaded” (if using OAuth)
✅ “230+ tools registered”

3. Test in MCP client:

Connect your MCP client
Look for 🔨 tools icon
Try a simple operation like “List my fulfillment policies”

4. Check token expiry: Look in your .env file:

EBAY_USER_TOKEN_EXPIRY=2024-12-31T23:59:59.000Z

Access tokens: Expire in 2 hours (auto-refresh)
Refresh tokens: Expire in 18 months

The server automatically refreshes expired access tokens using the refresh token.

How often do I need to re-authenticate?

It depends on your authentication method:With User Tokens (OAuth):

Access tokens: Expire every 2 hours
- ✅ Automatically refreshed by the server
- You don’t need to do anything
Refresh tokens: Expire after 18 months
- ⚠️ Need to re-run OAuth flow when they expire
- You’ll get an error when this happens
- Solution: Run npm run setup again

With Client Credentials:

Never expire
Automatically renewed by the server
No manual intervention needed

In practice:

Daily use: No action needed (tokens auto-refresh)
Every 18 months: Re-run npm run setup for new OAuth tokens
After credential changes: Run npm run setup again

Set a calendar reminder for 17 months after setup to regenerate tokens before they expire.

Is my API data secure?

Security measures in place:Credential Storage:

✅ Stored in .env file (local only)
✅ .gitignore prevents Git commits
✅ Never transmitted except to eBay APIs
✅ Environment variables not logged

Network Security:

✅ All API calls use HTTPS encryption
✅ Direct connection to eBay (no intermediaries)
✅ OAuth 2.0 industry standard
✅ Tokens are encrypted in transit

Best Practices:

Never commit .env to version control:

# Check .gitignore includes .env
cat .gitignore | grep .env

Set proper file permissions:
```
chmod 600 .env
```
Rotate credentials regularly:
- Regenerate every 90 days minimum
- Immediately if compromised
Use separate credentials per environment:
- Different keys for Sandbox vs Production
- Never use production keys for testing

Never share your Client Secret or tokens publicly, in screenshots, or in bug reports.

What happens if my tokens are stolen?

If you suspect credential compromise:Immediate actions:

Revoke tokens immediately:
- Visit eBay Developer Portal
- Delete or regenerate your application credentials
- This invalidates all tokens instantly
Generate new credentials:
- Create new Client ID and Secret
- Update your .env file
- Run npm run setup with new credentials
Check for unauthorized activity:
- Review your eBay account for unusual changes
- Check recent API activity in Developer Portal
- Look for unexpected listings or orders
Secure your system:
- Scan for malware
- Change passwords
- Review who has access to your system

Prevention:

Never commit .env to public repositories
Don’t share credentials in screenshots
Use file permissions: chmod 600 .env
Enable 2FA on your eBay account

Security Policy

Report security issues responsibly

Using the Server

How many API calls can I make per day?

Rate limits vary by authentication method and account type:With Client Credentials:

1,000 requests per day
Very limited
Only for testing/development

With User Tokens:

eBay Account Type	Daily Limit
Basic Seller	10,000 requests
Business Seller	25,000 requests
Enterprise Seller	50,000 requests

Per-second limits:

Varies by endpoint
Typically 10-50 requests/second
Server handles throttling automatically

What happens if I exceed limits:

Get “429 Too Many Requests” error
Limits reset after 24 hours
No permanent impact

How to increase limits:

Upgrade from client credentials to user tokens
Upgrade your eBay seller account tier
Optimize your API usage (caching, batching)

Monitor your usage and upgrade to user tokens for production use.

Can I use this server for multiple eBay accounts?

Yes, but with some configuration:Option 1: Multiple Instances

Clone the server multiple times
Configure each with different credentials
Run as separate MCP servers

# Structure
~/ebay-mcp-server-account1/
~/ebay-mcp-server-account2/
~/ebay-mcp-server-account3/

Option 2: Switch Credentials

Use different .env files
Switch between them as needed

# Maintain separate .env files
.env.account1
.env.account2

# Copy the one you need
cp .env.account1 .env

Option 3: Dynamic Configuration (Advanced)

Modify server to accept account parameter
Requires code changes
Not officially supported yet

MCP Client Configuration:

{
  "mcpServers": {
    "ebay-account1": {
      "command": "node",
      "args": ["/path/to/server1/build/index.js"]
    },
    "ebay-account2": {
      "command": "node",
      "args": ["/path/to/server2/build/index.js"]
    }
  }
}

Each server instance requires separate eBay Developer credentials and rate limits apply per account.

Does this work internationally?

Yes, the server works with eBay’s global marketplaces:Supported Marketplaces:

🇺🇸 United States (eBay.com)
🇬🇧 United Kingdom (eBay.co.uk)
🇩🇪 Germany (eBay.de)
🇦🇺 Australia (eBay.com.au)
🇨🇦 Canada (eBay.ca)
🇫🇷 France (eBay.fr)
🇮🇹 Italy (eBay.it)
🇪🇸 Spain (eBay.es)
And all other eBay marketplaces

How it works:

Use marketplace-specific parameters in API calls
Tools accept marketplace_id parameters
Same credentials work across marketplaces
Must be authorized to sell in that marketplace

Example:

// List item on eBay UK
marketplace_id: "EBAY_GB"

// List item on eBay Germany
marketplace_id: "EBAY_DE"

Requirements:

eBay seller account authorized for that marketplace
Appropriate marketplace settings in your account
Compliance with local regulations

Your eBay seller account determines which marketplaces you can access.

Can I automate recurring tasks?

Yes, but with important considerations:What you CAN automate:

✅ Inventory updates (bulk price changes, quantity updates)
✅ Order processing (marking shipped, adding tracking)
✅ Policy management (updating return/payment policies)
✅ Analytics reporting (daily/weekly reports)
✅ Listing refreshes (relisting ended items)

How to automate:Option 1: Through MCP Client

Use AI assistant to perform tasks on schedule
Set up reminders or recurring requests
Limited by client capabilities

Option 2: Custom Scripts (Advanced)

Write Node.js scripts using the MCP server
Schedule with cron (Linux/Mac) or Task Scheduler (Windows)
Requires programming knowledge

Option 3: Third-party Integration (Advanced)

Zapier, Make.com, or similar
Webhook integrations
May require custom development

Important limitations:

⚠️ Rate limits still apply - don’t exceed daily limits
⚠️ Monitor automation - check for errors regularly
⚠️ eBay policies - must comply with seller rules
⚠️ No official scheduling - server doesn’t include scheduler

Be careful with automation in Production - test thoroughly in Sandbox first.

What can't this server do?

Current limitations:eBay Functionality:

❌ Buyer operations - can’t browse or purchase items
❌ Messaging buyers - eBay Messaging API not included
❌ Returns management - limited return handling
❌ Disputes - can’t manage cases/disputes
❌ eBay Partner Network - no affiliate tracking

Technical Limitations:

❌ Real-time notifications - no webhook support yet
❌ File uploads - can’t upload images directly (use URLs)
❌ Bulk CSV import - no built-in CSV processing
❌ Historical data beyond API limits - eBay Sell APIs constraints apply
❌ Multi-account management - designed for single account

MCP Protocol Limitations:

❌ Persistent state - server is stateless
❌ Background jobs - no built-in job scheduling
❌ Real-time sync - changes aren’t pushed to client

Why these limitations exist:

Some features not available in eBay Sell APIs
MCP protocol design constraints
Project scope focused on core selling operations

Many limitations are planned for future versions. Check the Changelog for updates.

Troubleshooting & Support

My server isn't connecting to my MCP client

Common causes and solutions:1. Check the path in your config:

{
  "command": "node",
  "args": [
    "/absolute/path/to/ebay-mcp-server/build/index.js"
  ]
}

Must be absolute path, not relative
Check the file exists: ls /path/to/build/index.js
No tilde (~) - use full path

2. Ensure server is built:

cd ebay-mcp-server
npm run build
ls build/index.js  # Should exist

3. Restart MCP client:

Fully quit (Cmd+Q on Mac)
Reopen application
Check for 🔨 tools icon

4. Check environment variables:

Pass credentials in config’s env section
Or ensure .env file exists in server directory

Full Guide

See detailed troubleshooting steps

I'm getting rate limit errors

You’ve exceeded your daily API request limit.Quick solutions:

Upgrade to user tokens (if using client credentials):
```
npm run setup
```
This increases from 1,000 to 10,000+ requests/day
Wait for reset:
- Rate limits reset every 24 hours
- Check when your limit resets in eBay Developer Portal
Optimize API usage:
- Cache responses when possible
- Use bulk operations instead of individual calls
- Avoid unnecessary polling
Upgrade eBay account:
- Business sellers get 25,000 requests/day
- Enterprise sellers get 50,000 requests/day

Rate Limit Guide

Learn more about managing rate limits

Where can I get help?

Multiple support channels:Documentation:

📚 Full Documentation - Start here
🔧 Troubleshooting Guide - Common issues
❓ This FAQ - Quick answers

Community Support:

💬 GitHub Discussions - Ask questions
🐛 GitHub Issues - Report bugs
📖 eBay Developer Forums - eBay Sell APIs help

eBay Resources:

🌐 eBay Developer Portal - API documentation
📞 eBay Developer Support - Official support
📊 eBay Sell APIs Status - System status

When asking for help, include:

Error messages (complete, not truncated)
Steps to reproduce the issue
Your environment (OS, Node version, MCP client)
Configuration (without secrets!)

Never share your Client Secret, access tokens, or refresh tokens when asking for help.

How do I report bugs or request features?

Use GitHub Issues for all bug reports and feature requests:For Bugs:

Visit GitHub Issues
Search existing issues first
Click “New Issue” → “Bug Report”
Fill in the template:
- Description of the bug
- Steps to reproduce
- Expected vs actual behavior
- Environment info
- Logs and error messages

For Feature Requests:

Visit GitHub Issues
Search if already requested
Click “New Issue” → “Feature Request”
Describe:
- What feature you want
- Why it would be useful
- How it should work
- Alternatives considered

For Security Issues:

Don’t create public issues
Follow the Security Policy
Report privately to maintainers

Good bug reports with reproduction steps get fixed faster!

Advanced Topics

Can I contribute to the project?

Yes! Contributions are welcome and appreciated.Ways to contribute:1. Code Contributions:

Fix bugs
Add new features
Improve performance
Add tests

2. Documentation:

Fix typos
Improve clarity
Add examples
Translate to other languages

3. Testing:

Report bugs
Test new features
Verify fixes

4. Community:

Answer questions in Discussions
Help other users
Share your use cases

Getting started:

Fork the repository
Read the contributing guide:
- CONTRIBUTING.md
Set up development environment
Make your changes
Submit a pull request

Requirements:

Follow code style guidelines
Add tests for new features
Update documentation
Sign commits (DCO)

Contributing Guide

Read the full contributing guide

How is this different from other eBay integrations?

Key differentiators:1. Model Context Protocol (MCP):

Modern AI-first architecture
Natural language interface
Works with multiple AI assistants
Standardized protocol

2. Comprehensive Coverage:

230+ tools (most complete eBay integration)
99.1% API coverage
All major seller operations
Regularly updated

3. Developer Experience:

Simple setup (10 minutes)
Interactive configuration wizard
Excellent documentation
Well-tested (870+ tests)

4. Open Source:

Apache 2.0 license
Free forever
Community-driven
Transparent development

Compared to:Traditional APIs:

More coding required
Manual API calls
No AI integration

eBay Official Tools:

Different use cases
Web-based interfaces
Not API-focused

Other Integrations:

Often limited scope
May lack OAuth support
Varying quality/maintenance

This is the most comprehensive MCP server for eBay’s Sell APIs.

Is this project actively maintained?

Yes, the project is actively maintained and developed.Indicators of active maintenance:Regular Updates:

Frequent commits and releases
Bug fixes addressed promptly
New features added regularly
Dependencies kept up-to-date

Community Engagement:

Issues responded to within 24-48 hours
Pull requests reviewed and merged
Active GitHub Discussions
Regular documentation updates

Quality Standards:

870+ tests maintained
99%+ function coverage
Continuous integration (CI)
Regular security audits

Roadmap:

Planned features documented
Clear versioning (semantic versioning)
Changelog maintained
Transparent development

How to check:

Visit GitHub repository
Check commit frequency
Review closed/open issues
See Changelog

The project follows an open development model. You can see all activity on GitHub.

What's on the roadmap?

Planned features and improvements:Near-term (Next 3 months):

🔔 Webhook support for real-time notifications
📦 Docker images for easier deployment
🌐 Additional marketplace support
📊 Enhanced analytics and reporting
🎨 Image upload support

Mid-term (3-6 months):

💬 eBay Messaging API integration
🔄 Automated backup and restore
📈 Performance optimizations
🧪 Additional testing tools
📚 More code examples

Long-term (6-12 months):

🤖 AI-powered listing optimization
📊 Business intelligence features
🔌 Additional MCP client support
🌍 Multi-language documentation
🎯 Advanced automation features

How to influence roadmap:

👍 Upvote feature requests on GitHub
💡 Suggest new features in Discussions
🤝 Contribute pull requests
💬 Share your use cases

Changelog

See what’s been released

Still Have Questions?

Troubleshooting

Detailed solutions to common problems

GitHub Discussions

Ask the community

Full Documentation

Explore all documentation

API Reference

Complete tool documentation

Getting Started

Authentication

Core Features

Guides

MCP Integration

Advanced

Support

Getting Started

Learn More

Integration Guides

Installation & Setup

Detailed Guide

Authentication & Security

Security Policy

Using the Server

Troubleshooting & Support

Full Guide

Rate Limit Guide

Advanced Topics

Contributing Guide

Changelog

Still Have Questions?

Troubleshooting

GitHub Discussions

Full Documentation

API Reference

Getting Started

Authentication

Core Features

Guides

MCP Integration

Advanced

Support

​Getting Started

Learn More

Integration Guides

​Installation & Setup

Detailed Guide

​Authentication & Security

Security Policy

​Using the Server

​Troubleshooting & Support

Full Guide

Rate Limit Guide

​Advanced Topics

Contributing Guide

Changelog

​Still Have Questions?

Troubleshooting

GitHub Discussions

Full Documentation

API Reference

Getting Started

Installation & Setup

Authentication & Security

Using the Server

Troubleshooting & Support

Advanced Topics

Still Have Questions?