ebay-mcp-remote-edition

v3.1.2

Published

3 days ago

Remote + Local MCP server for eBay APIs - provides access to eBay developer functionality through MCP (Model Context Protocol)

0High
0Medium
0Low

mrnajiboy

mcp ebay ebay-api model-context-protocol ai-tools ai llm mcp documentation api ebay server backend

eBay MCP — Remote Edition

A Model Context Protocol (MCP) server providing AI assistants with comprehensive access to eBay's Sell APIs. 325+ tools covering inventory management, order fulfillment, marketing campaigns, analytics, developer tools, and more.

API Coverage: 100% of eBay Sell APIs (270+ unique endpoints)

Overview

This project extends Yosef Hayim's eBay MCP with a full hosted, multi-user deployment mode while keeping the original local STDIO mode intact. The key additions are:

Hosted Streamable HTTP mode — deploy to Render (or any Node.js host) and serve multiple users from one instance
MCP OAuth 2.1 authorization server — full browser-based eBay login with automatic token management; Cline and other OAuth-aware clients connect with zero manual token pasting
Environment-scoped route trees — /sandbox/mcp and /production/mcp hard-bind their eBay environment; no query param needed
Cloudflare KV / Upstash Redis token and session storage for persistent multi-user auth
Admin session management — inspect, revoke, or delete sessions via authenticated endpoints
TTL-aligned records — every stored record (OAuth state, auth code, session, user token) carries an expiresAt timestamp and a matching KV/Redis TTL so storage and application expiry are always in sync

⚠️ Disclaimer

This is an open-source project provided "as is" without warranty of any kind. The authors accept no responsibility or liability for any damages arising from use of this software. This project is not affiliated with, endorsed by, or sponsored by eBay Inc. Test thoroughly in eBay's sandbox before using in production.

Choose a runtime mode

| Mode | Transport | Best for | |------|-----------|----------| | Local STDIO | stdin/stdout | Single-user local AI client (Claude Desktop, Cline, Cursor, etc.) | | Hosted HTTP | Streamable HTTP | Multi-user server deployment; remote MCP clients |

Both modes use the same eBay tools. The local mode reads credentials from environment variables or a .env file. The hosted mode handles multi-user OAuth server-side and authenticates clients with session tokens.

Prerequisites

All modes:

Node.js ≥ 18.0.0
pnpm (or npm — npm install -g pnpm)
An eBay Developer Account

Getting eBay credentials:

Log in to the eBay Developer Portal
Create an application and copy your App ID (Client ID) and Cert ID (Client Secret)
Under User Tokens → Add RuName, register your OAuth callback URL and copy the generated RuName string

EBAY_RUNAME is the RuName string eBay generates, not the callback URL itself. It looks like YourApp-YourApp-SBX-abcdefghi. The callback URL is set separately (see below).

HTTPS callback URL (required by eBay)

eBay requires an HTTPS callback URL for OAuth. For local development, use mkcert:

brew install mkcert nss
mkcert -install
mkcert ebay-local.test
echo "127.0.0.1  ebay-local.test" | sudo tee -a /etc/hosts

Register https://ebay-local.test:3000/oauth/callback in the eBay Developer Portal as your Accept URL. Then add to .env:

PUBLIC_BASE_URL=https://ebay-local.test:3000
EBAY_LOCAL_TLS_CERT_PATH=/path/to/ebay-local.test.pem
EBAY_LOCAL_TLS_KEY_PATH=/path/to/ebay-local.test-key.pem

⚠️ Trust the mkcert CA in Node.js (required for MCP clients like Cline)

VS Code's extension host (where Cline runs) uses Node.js for outbound HTTPS requests. Node.js does not automatically read macOS's system keychain, so the ebay-local.test certificate is not trusted by default. This causes the OAuth token exchange (POST /sandbox/token) to fail silently — the browser flow completes, the "Open in VS Code" page appears, but Cline never receives a session token.

Fix — run these two commands once, then fully quit and reopen VS Code:

# 1. Set for the current macOS session (affects all Dock/Spotlight-launched apps):
launchctl setenv NODE_EXTRA_CA_CERTS "$(mkcert -CAROOT)/rootCA.pem"

# 2. Create a LaunchAgent so it persists across reboots:
cat > ~/Library/LaunchAgents/com.local.mkcert-node-trust.plist <<'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>com.local.mkcert-node-trust</string>
  <key>ProgramArguments</key>
  <array>
    <string>launchctl</string><string>setenv</string>
    <string>NODE_EXTRA_CA_CERTS</string>
    <string>/Users/YOUR_USERNAME/Library/Application Support/mkcert/rootCA.pem</string>
  </array>
  <key>RunAtLoad</key><true/>
</dict>
</plist>
EOF
launchctl load ~/Library/LaunchAgents/com.local.mkcert-node-trust.plist

# 3. For terminal-launched VS Code — add to ~/.zshrc:
echo 'export NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem"' >> ~/.zshrc

Replace YOUR_USERNAME with your actual macOS username in the plist, or use the full path printed by mkcert -CAROOT.

After running these commands and fully quitting VS Code (Cmd+Q on macOS) and reopening it, Cline's extension host will trust the ebay-local.test certificate and the MCP OAuth flow will complete successfully.

Verify the fix works (without restarting VS Code):

NODE_EXTRA_CA_CERTS="$(mkcert -CAROOT)/rootCA.pem" node -e "
  require('https').get('https://ebay-local.test:3000/health', r => console.log('TLS OK — status:', r.statusCode)).on('error', e => console.error('TLS FAIL:', e.message));
"
# Expected: TLS OK — status: 200

For hosted deployments, register your server's public HTTPS URL instead (e.g. https://your-server.com/oauth/callback).

Local mode setup

Install

Option A — npm global install (no build step):

npm install -g ebay-mcp-remote-edition

Option B — clone and build (for contributors or self-hosting):

git clone https://github.com/mrnajiboy/ebay-mcp-remote-edition.git
cd ebay-mcp-remote-edition
pnpm install
pnpm run build

Configure credentials

Create a .env file in the project root (see .env.example):

EBAY_CLIENT_ID=your_client_id
EBAY_CLIENT_SECRET=your_client_secret
EBAY_RUNAME=your_runame_string
EBAY_ENVIRONMENT=sandbox           # or production
EBAY_MARKETPLACE_ID=EBAY_US        # optional, defaults to EBAY_US
EBAY_CONTENT_LANGUAGE=en-US        # optional, defaults to en-US

# Populated by the setup wizard:
EBAY_USER_REFRESH_TOKEN=

Authentication tiers:

| Method | Rate limit | How | |--------|-----------|-----| | Client credentials (default) | 1,000 req/day | Just set EBAY_CLIENT_ID + EBAY_CLIENT_SECRET | | User tokens (recommended) | 10,000–50,000 req/day | Run the setup wizard to complete OAuth and populate EBAY_USER_REFRESH_TOKEN |

Run the setup wizard

The interactive wizard guides you through environment selection, credential entry, OAuth login, and MCP client configuration:

pnpm run setup

Options:

--quick — skip optional steps
--diagnose — run connectivity and token checks only

After completing OAuth, the wizard writes EBAY_USER_REFRESH_TOKEN to .env and optionally configures Claude Desktop automatically.

Local client configuration

For direct STDIO usage, configure your MCP client to launch the server as a subprocess. All clients use the same JSON pattern:

Using npm (no clone needed):

{
  "mcpServers": {
    "ebay": {
      "command": "npx",
      "args": ["-y", "ebay-mcp-remote-edition"],
      "env": {
        "EBAY_CLIENT_ID": "YOUR_CLIENT_ID",
        "EBAY_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "EBAY_ENVIRONMENT": "sandbox",
        "EBAY_RUNAME": "YOUR_RUNAME",
        "EBAY_USER_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN"
      }
    }
  }
}

Using a local build:

{
  "mcpServers": {
    "ebay": {
      "command": "node",
      "args": ["/absolute/path/to/ebay-mcp-remote-edition/build/index.js"],
      "env": {
        "EBAY_CLIENT_ID": "YOUR_CLIENT_ID",
        "EBAY_CLIENT_SECRET": "YOUR_CLIENT_SECRET",
        "EBAY_ENVIRONMENT": "sandbox",
        "EBAY_RUNAME": "YOUR_RUNAME",
        "EBAY_USER_REFRESH_TOKEN": "YOUR_REFRESH_TOKEN"
      }
    }
  }
}

Config file locations by client:

| Client | Config file | |--------|-------------| | Cline | ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json | | Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json | | Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json | | Cursor (global) | ~/.cursor/mcp.json | | Cursor (project) | .cursor/mcp.json |

Zed, Windsurf, Continue.dev, Roo Code, and Amazon Q follow the same mcpServers JSON shape.

Hosted mode setup

The hosted HTTP server exposes environment-scoped MCP and OAuth endpoints, handles eBay OAuth server-side, and issues session tokens to MCP clients.

Hosted environment variables

# Server
PORT=3000
MCP_HOST=0.0.0.0
PUBLIC_BASE_URL=https://your-server.com

# eBay credentials (prefer secret file below instead of raw env)
EBAY_DEFAULT_ENVIRONMENT=production    # sandbox or production

# Persistent token/session storage backend (required for multi-user hosted mode)
EBAY_TOKEN_STORE_BACKEND=cloudflare-kv # cloudflare-kv | upstash-redis | memory

# Cloudflare KV (when EBAY_TOKEN_STORE_BACKEND=cloudflare-kv)
CLOUDFLARE_ACCOUNT_ID=
CLOUDFLARE_KV_NAMESPACE_ID=
CLOUDFLARE_API_TOKEN=

# Upstash Redis (when EBAY_TOKEN_STORE_BACKEND=upstash-redis)
UPSTASH_REDIS_REST_URL=
UPSTASH_REDIS_REST_TOKEN=

# Security
ADMIN_API_KEY=              # required for admin session endpoints
OAUTH_START_KEY=            # optional; protects /oauth/start with a shared secret

# Session TTL (optional; default 30 days)
SESSION_TTL_SECONDS=2592000

# Logging
EBAY_LOG_LEVEL=info
EBAY_MARKETPLACE_ID=EBAY_US
EBAY_CONTENT_LANGUAGE=en-US

# Path to secret file (see below)
EBAY_CONFIG_FILE=/etc/secrets/ebay-config.json

Use EBAY_TOKEN_STORE_BACKEND=memory only for local development or tests. All OAuth state, session tokens, and user tokens are lost on restart.

Secret file

Store eBay credentials in a mounted secret file rather than raw environment variables. On Render, create a Secret File named ebay-config.json mounted at /etc/secrets/ebay-config.json:

{
  "production": {
    "clientId": "PROD_CLIENT_ID",
    "clientSecret": "PROD_CLIENT_SECRET",
    "redirectUri": "YOUR_PRODUCTION_RUNAME"
  },
  "sandbox": {
    "clientId": "SANDBOX_CLIENT_ID",
    "clientSecret": "SANDBOX_CLIENT_SECRET",
    "redirectUri": "YOUR_SANDBOX_RUNAME"
  }
}

Deploy to Render

Connect your repo to Render as a Web Service
Set Build command:
```
pnpm install && pnpm run build
```
Set Start command:
```
pnpm run start:http
```
Add the environment variables listed above
Add the ebay-config.json secret file

The server starts on the port Render assigns via $PORT and logs the active KV backend on startup.

OAuth flows

eBay requires a single registered callback URL per application. The hosted server registers /oauth/callback at the root and recovers the environment from the stored OAuth state record.

Start an OAuth flow (browser):

GET /sandbox/oauth/start         # always sandbox
GET /production/oauth/start      # always production

If OAUTH_START_KEY is set, include it as a query parameter or header:

GET /sandbox/oauth/start?key=YOUR_OAUTH_START_KEY
# or header:  X-OAuth-Start-Key: YOUR_OAUTH_START_KEY

After a successful login, the callback page displays your session token, eBay access token, and eBay refresh token with one-click copy buttons.

Session token TTL schedule:

| Record | expiresAt field | Backend TTL | |--------|-------------------|-------------| | OAuth state | 15 minutes | 15 minutes | | MCP auth code | 10 minutes | 10 minutes | | Session | 30 days (configurable) | Matches SESSION_TTL_SECONDS | | User token record | eBay refresh token expiry (fallback: 18 months) | Matches token expiry |

MCP endpoints

Environment-scoped (recommended):

POST/GET/DELETE /sandbox/mcp
POST/GET/DELETE /production/mcp

Each scoped path includes its own OAuth 2.1 discovery document:

GET /sandbox/.well-known/oauth-authorization-server
GET /production/.well-known/oauth-authorization-server

Legacy auto-detect (backward-compatible):

POST/GET/DELETE /mcp        # resolves environment from ?env= or EBAY_DEFAULT_ENVIRONMENT

Authentication behavior:

GET /mcp (or scoped variant) without a valid Bearer token redirects the browser to the matching oauth/start URL
POST /mcp without a valid Bearer token returns a structured 401 JSON with an authorization_url field
All requests supply a session token via Authorization: Bearer <session-token>

Other utility endpoints:

GET  /health                           # Server health check (no auth required)
GET  /whoami                           # Session identity; requires Bearer token
GET  /admin/session/:sessionToken      # View session; requires X-Admin-API-Key
POST /admin/session/:sessionToken/revoke  # Revoke session
DELETE /admin/session/:sessionToken    # Delete session

/whoami response:

{
  "userId": "...",
  "environment": "sandbox",
  "createdAt": "2026-03-23T08:00:00.000Z",
  "expiresAt": "2026-04-22T08:00:00.000Z",
  "lastUsedAt": "2026-03-23T09:30:00.000Z",
  "revokedAt": null
}

Remote client configuration

Replace https://your-server.com with your actual PUBLIC_BASE_URL.

Cline (automatic OAuth — no manual token needed)

Cline supports MCP OAuth 2.1 discovery natively. It fetches the discovery document, registers itself, opens the eBay browser login, exchanges the auth code for a session token, and stores it — all automatically.

{
  "mcpServers": {
    "ebay-sandbox": {
      "url": "https://your-server.com/sandbox/mcp"
    },
    "ebay-production": {
      "url": "https://your-server.com/production/mcp"
    }
  }
}

What Cline does automatically:

Fetches /.well-known/oauth-authorization-server for the scoped path
Registers at POST /sandbox/register (or /production/register)
Your browser opens GET /sandbox/authorize, which redirects to eBay login
After you grant access, eBay redirects to /oauth/callback, which issues an auth code
Cline exchanges the code at POST /sandbox/token for a session token and stores it
All subsequent /sandbox/mcp requests authenticate automatically

Claude Desktop and Cursor (Bearer token)

Claude Desktop and most other remote MCP clients require a pre-obtained session token. Complete the browser OAuth flow first:

Open https://your-server.com/sandbox/oauth/start (or /production/oauth/start) in a browser
Log in with your eBay account
Copy the session token from the confirmation page

Then configure your client:

{
  "mcpServers": {
    "ebay-sandbox": {
      "url": "https://your-server.com/sandbox/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SESSION_TOKEN"
      }
    }
  }
}

Make / Zapier / TypingMind and similar platforms

Open https://your-server.com/sandbox/oauth/start in a browser and complete eBay login
Copy the session token from the confirmation page
Paste it as the API Key / Bearer token in the platform's MCP connector settings
Set the MCP endpoint URL to https://your-server.com/sandbox/mcp

Available tools

325+ tools across all eBay Sell API categories:

Account Management
Inventory Management
Order Fulfillment
Marketing & Promotions
Analytics & Reporting
Communication (messages, feedback, notifications, negotiation)
Metadata & Taxonomy
Developer Tools (key management, analytics)
Auth / Token helper tools

Full tool source: src/tools/definitions/

Development

Commands reference

| Command | Description | |---------|-------------| | pnpm run build | Compile TypeScript to JavaScript | | pnpm start | Run local STDIO MCP server | | pnpm run start:http | Run hosted HTTP MCP server | | pnpm run dev | Local STDIO server with hot reload | | pnpm run dev:http | Hosted HTTP server with hot reload | | pnpm test | Run test suite | | pnpm run setup | Interactive local setup wizard | | pnpm run sync | Download latest eBay OpenAPI specs and regenerate types | | pnpm run diagnose | Check configuration and connectivity | | pnpm run typecheck | Run TypeScript type checking | | pnpm run check | Typecheck + lint + format check | | pnpm run fix | Auto-fix lint and format issues |

`pnpm run sync`

Downloads the latest eBay OpenAPI specs, regenerates TypeScript types, and reports implemented vs missing endpoints. Run this when you want to pick up new eBay API surface:

pnpm run sync
pnpm run typecheck
pnpm run build

Review the diff, commit the generated changes you want to keep, and deploy.

Local env management

For local development, standard runtime scripts automatically load .env via dotenvx. Hosted platforms should provide environment variables directly — the server detects hosted environments (e.g. RENDER=true) and skips local file loading.

pnpm run env:encrypt   # encrypt .env for safe sharing
pnpm run env:decrypt   # decrypt

Logging

EBAY_LOG_LEVEL=debug             # error | warn | info | debug
EBAY_ENABLE_FILE_LOGGING=true    # write logs to files

Testing & validation

# Build and type check
pnpm run build
pnpm run typecheck

# Run the test suite
pnpm test

# Check connectivity and token status
pnpm run diagnose

# Verify hosted server health
curl https://your-server.com/health

# Verify a session token
curl -H "Authorization: Bearer <session-token>" https://your-server.com/whoami

# Test MCP endpoint returns auth challenge when no token is provided
curl -X POST https://your-server.com/sandbox/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
# → should return 401 with authorization_url

Troubleshooting

Hosted MCP returns 406

Include the correct Accept header in your MCP client:

Accept: application/json, text/event-stream

OAuth callback: "Invalid or expired OAuth state"

OAuth state records expire in 15 minutes. If you see this error, restart the browser OAuth flow.

Token verification fails on existing refresh token

Refresh tokens expire after ~18 months or can be revoked by eBay (password changes, etc.). Run the setup wizard again to obtain a new one:

pnpm run setup

In hosted mode, start a new browser OAuth flow at /sandbox/oauth/start or /production/oauth/start.

Session token no longer works in hosted mode

Check whether the session was revoked or expired:

curl -H "Authorization: Bearer <token>" https://your-server.com/whoami

Revoke exposed session tokens via the admin endpoint:

curl -X POST https://your-server.com/admin/session/<token>/revoke \
  -H "X-Admin-API-Key: YOUR_ADMIN_API_KEY"

Security checklist

Do not commit .env or session tokens to version control
Protect /oauth/start and /admin/* with OAUTH_START_KEY and ADMIN_API_KEY
Keep /oauth/callback publicly reachable (eBay redirects to it after login)
Keep /health reachable if Render uses it for health checks
For production-grade isolation, optionally place /, /oauth/start, and /admin/* behind Cloudflare Access
Rotate exposed eBay client secrets and update your secret file

Resources

License

MIT — see LICENSE