eBay API MCP Server

https://github.com/yosefhayim/ebay-api-mcp-server
Admin
A Model Context Protocol server that provides AI assistants with comprehensive access to eBay's...
Tokens:11,022
Snippets:31
Trust Score:4
License:MIT
Update:10 months ago
Show doc for...
Tokens:
Raw
================
LIBRARY RULES
================
- Always set environment variables in .env file before starting the server
- Use ebay_get_oauth_url to generate authorization URLs for user tokens
- Store sensitive credentials in .env file, never commit them to version control
- Run automatic setup script for MCP client configuration: npm run auto-setup
- Use TypeScript for better type safety when working with eBay API responses
- All 140+ tools follow the naming convention: ebay_[category]_[action]
- Check token expiry with ebay_validate_token_expiry before making API calls
- Use sandbox environment (EBAY_ENVIRONMENT=sandbox) for testing
- Production environment requires eBay App Review approval
- OAuth tokens expire after 2 hours, refresh tokens last 18 months
- Inventory tools require SKU as primary identifier
- Use bulk operations for efficiency when managing multiple items
- Marketing tools require marketplace_id parameter for campaign targeting
- Order fulfillment requires shipping fulfillment creation before marking shipped
- Always validate eBay API rate limits when building automation

================
CODE SNIPPETS
================
### Install eBay API MCP Server from Source

Source: https://github.com/yosefhayim/ebay-api-mcp-server/blob/main/README.md

Installs the eBay API MCP Server by cloning the repository from GitHub, installing dependencies, and building the project. This method is useful for development or if you need to work with the source code directly.

```bash
git clone https://github.com/YosefHayim/ebay-mcp.git
cd ebay-mcp
npm install
npm run build
```

--------------------------------

### Install eBay API MCP Server using npm

Source: https://github.com/yosefhayim/ebay-api-mcp-server/blob/main/README.md

Installs the eBay API MCP Server globally using npm, the recommended installation method. This command fetches the latest version from the npm registry and makes it available system-wide.

```bash
npm install -g ebay-mcp
```

--------------------------------

### Configure MCP Server for eBay API (Local Install)

Source: https://github.com/yosefhayim/ebay-api-mcp-server/blob/main/README.md

This JSON configuration is for users who have installed the eBay MCP server locally from source. It defines the command to execute the local Node.js script and the required environment variables for authentication. The 'args' field needs to point to the correct absolute path of the build index file.

```json
{
  "mcpServers": {
    "ebay": {
      "command": "node",
      "args": ["/absolute/path/to/ebay-mcp/build/index.js"],
      "env": {
        "EBAY_CLIENT_ID": "your_client_id",
        "EBAY_CLIENT_SECRET": "your_client_secret",
        "EBAY_ENVIRONMENT": "sandbox"
      }
    }
  }
}
```

--------------------------------

### Interactive Setup Wizard with TypeScript

Source: https://context7.com/yosefhayim/ebay-api-mcp-server/llms.txt

Configure eBay MCP Server credentials interactively using TypeScript CLI wizard with prompts library. Collects eBay Client ID, Client Secret, environment selection (sandbox/production), redirect URI, and user refresh token, then saves configuration to .env file. Requires prompts, chalk, and fs modules.

```typescript
import prompts from 'prompts';
import chalk from 'chalk';
import fs from 'fs';
import path from 'path';

// Run interactive setup
async function runSetup() {
  console.log(chalk.bold.red('\n╔═══════════════════════════════════╗'));
  console.log(chalk.bold.red('║') + chalk.bold.white('   eBay MCP Server Setup Wizard   ') + chalk.bold.red('║'));
  console.log(chalk.bold.red('╚═══════════════════════════════════╝\n'));

  const responses = await prompts([
    {
      type: 'text',
      name: 'clientId',
      message: 'Enter your eBay Client ID:',
      validate: value => value.length > 0 || 'Client ID is required'
    },
    {
      type: 'password',
      name: 'clientSecret',
      message: 'Enter your eBay Client Secret:',
      validate: value => value.length > 0 || 'Client Secret is required'
    },
    {
      type: 'select',
      name: 'environment',
      message: 'Select environment:',
      choices: [
        { title: 'Sandbox (Testing)', value: 'sandbox' },
        { title: 'Production (Live)', value: 'production' }
      ]
    },
    {
      type: 'text',
      name: 'redirectUri',
      message: 'Enter your eBay RuName (optional):',
      initial: ''
    },
    {
      type: 'text',
      name: 'userRefreshToken',
      message: 'Enter your User Refresh Token (optional):',
      initial: ''
    }
  ]);

  // Write to .env file
  const envContent = `
EBAY_CLIENT_ID=${responses.clientId}
EBAY_CLIENT_SECRET=${responses.clientSecret}
EBAY_ENVIRONMENT=${responses.environment}
EBAY_REDIRECT_URI=${responses.redirectUri}
EBAY_USER_REFRESH_TOKEN=${responses.userRefreshToken}
`.trim();

  fs.writeFileSync('.env', envContent);
  console.log(chalk.green('\n✓ Configuration saved to .env'));
}

// Run with: npm run setup
```

--------------------------------

### Docker Deployment Commands with Bash

Source: https://context7.com/yosefhayim/ebay-api-mcp-server/llms.txt

Deploy and manage eBay MCP Server using Docker Compose with bash commands. Includes building Docker image, starting/stopping services, viewing logs, and automatic .env configuration loading. Requires Docker and docker-compose installed.

```bash
# Build Docker image
docker-compose build

# Start the server
docker-compose up -d

# View logs
docker-compose logs -f

# Stop the server
docker-compose down

# Configuration via .env file is automatically used
```

--------------------------------

### Configure eBay API MCP Server Manually

Source: https://github.com/yosefhayim/ebay-api-mcp-server/blob/main/README.md

Configures the eBay API MCP Server by copying an example environment file and then editing it with your eBay API credentials. This manual approach allows for direct control over the configuration settings.

```bash
cp .env.example .env
# Edit .env with your credentials
npm run auto-setup
```

--------------------------------

### Initialize HTTP API Client with eBay Configuration

Source: https://context7.com/yosefhayim/ebay-api-mcp-server/llms.txt

Creates an authenticated eBay API client instance with configuration credentials. The client handles all HTTP requests (GET, POST, PUT, DELETE) with automatic error formatting and authentication management. Requires valid eBay sandbox or production credentials.

```typescript
import { EbayApiClient } from './api/client.js';
import { EbayConfig } from './types/ebay.js';

const config: EbayConfig = {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  environment: 'sandbox'
};

const client = new EbayApiClient(config);

if (client.isAuthenticated()) {
  console.log('Client is authenticated');
}
```

--------------------------------

### HTTP API Client Usage

Source: https://context7.com/yosefhayim/ebay-api-mcp-server/llms.txt

Demonstrates the basic usage of the HTTP API client for making authenticated requests to eBay APIs, including GET, POST, PUT, and DELETE operations, as well as authentication checks.

```APIDOC
## HTTP API Client

### Description
Base client for making authenticated requests to eBay APIs with automatic error handling.

### Method
POST, GET, PUT, DELETE

### Endpoint
Various eBay API endpoints

### Parameters
#### Query Parameters
- **limit** (number) - Optional - The maximum number of results to return.
- **offset** (number) - Optional - The number of results to skip.

#### Request Body
- **(object)** - Varies depending on the endpoint. For example, a POST request to create an offer requires `sku`, `marketplaceId`, `format`, `listingPolicies`, and `pricingSummary`.

### Request Example (GET)
```json
await client.get('/sell/inventory/v1/inventory_item', {
  limit: 10,
  offset: 0
});
```

### Request Example (POST)
```json
await client.post('/sell/inventory/v1/offer', {
  sku: 'SKU-123',
  marketplaceId: 'EBAY_US',
  format: 'FIXED_PRICE',
  listingPolicies: { /* ... */ },
  pricingSummary: { price: { value: '19.99', currency: 'USD' } }
});
```

### Request Example (PUT)
```json
await client.put('/sell/inventory/v1/inventory_item/SKU-123', {
  product: { title: 'Updated Title' }
});
```

### Request Example (DELETE)
```json
await client.delete('/sell/inventory/v1/offer/12345');
```

### Response
#### Success Response (200)
- **(any)** - The response body depends on the specific API endpoint called.

#### Error Handling
- Errors are formatted with eBay API error messages.

### Response Example
```json
// For GET request
{
  // ... array of inventory items or other data
}

// For POST/PUT request
{
  // ... confirmation or created/updated resource
}

// For DELETE request
{
  // ... empty or confirmation
}
```
```

--------------------------------

### Manage eBay eDelivery International Shipping with TypeScript

Source: https://context7.com/yosefhayim/ebay-api-mcp-server/llms.txt

Manage international shipping packages and bundles using the eDelivery API. This snippet demonstrates how to get shipping services, create and confirm packages, create shipping bundles, and retrieve actual shipping costs.

```typescript
import { EDeliveryApi } from './api/other/edelivery.js';
import { EbayApiClient } from './api/client.js';

const client = new EbayApiClient(config);
const edelivery = new EDeliveryApi(client);

try {
  // Get shipping services
  const services = await edelivery.getShippingServices({
    destination_country_code: 'GB',
    origin_country_code: 'US'
  });
  console.log('Available services:', services.shippingServices?.length);

  // Create a package
  const packageData = await edelivery.createPackage({
    orderLineItemId: 'line-item-123',
    packageDetails: {
      weight: { value: 2.5, unit: 'KILOGRAM' },
      dimensions: {
        length: 30,
        width: 20,
        height: 15,
        unit: 'CENTIMETER'
      }
    },
    shippingServiceCode: 'USPS_PRIORITY_MAIL_INTERNATIONAL'
  });
  console.log('Package created:', packageData.packageId);

  // Get package details
  const pkg = await edelivery.getPackage(packageData.packageId!);
  console.log('Package status:', pkg.status);

  // Confirm package for shipping
  await edelivery.confirmPackage(packageData.packageId!);
  console.log('Package confirmed');

  // Create a shipping bundle
  const bundle = await edelivery.createBundle({
    packages: [packageData.packageId!],
    shippingServiceCode: 'USPS_PRIORITY_MAIL_INTERNATIONAL'
  });
  console.log('Bundle created:', bundle.bundleId);

  // Get actual shipping costs
  const costs = await edelivery.getActualCosts({
    packageIds: [packageData.packageId!]
  });
  console.log('Shipping cost:', costs.totalCost?.value, costs.totalCost?.currency);

} catch (error) {
  console.error('eDelivery operation failed:', error.message);
}

```

--------------------------------

### Execute HTTP Requests with eBay API Client

Source: https://context7.com/yosefhayim/ebay-api-mcp-server/llms.txt

Demonstrates GET, POST, PUT, and DELETE HTTP methods for eBay API endpoints. Each method automatically handles authentication headers and formats eBay API error responses. Includes error handling for API failures with formatted error messages.

```typescript
try {
  // GET request with query parameters
  const items = await client.get('/sell/inventory/v1/inventory_item', {
    limit: 10,
    offset: 0
  });

  // POST request with body
  const offer = await client.post('/sell/inventory/v1/offer', {
    sku: 'SKU-123',
    marketplaceId: 'EBAY_US',
    format: 'FIXED_PRICE',
    listingPolicies: { /* ... */ },
    pricingSummary: { price: { value: '19.99', currency: 'USD' } }
  });

  // PUT request to update resource
  await client.put('/sell/inventory/v1/inventory_item/SKU-123', {
    product: { title: 'Updated Title' }
  });

  // DELETE request
  await client.delete('/sell/inventory/v1/offer/12345');
} catch (error) {
  console.error('API Error:', error.message);
}
```

--------------------------------

### eBay OAuth 2.0 Authentication with Smart Fallback (TypeScript)

Source: https://context7.com/yosefhayim/ebay-api-mcp-server/llms.txt

Manages OAuth 2.0 token for eBay API access using client credentials and user tokens with automatic fallback. It requires eBay configuration details and provides methods to get, check, and generate consent URLs for tokens. Error handling for authentication failures is included.

```typescript
import { EbayOAuthClient } from './auth/oauth.js';
import { EbayConfig } from './types/ebay.js';

const config: EbayConfig = {
  clientId: process.env.EBAY_CLIENT_ID!,
  clientSecret: process.env.EBAY_CLIENT_SECRET!,
  environment: 'sandbox', // or 'production'
  redirectUri: 'your-runame', // eBay RuName (e.g., "YourName-AppName-xxxxx-xxxxxx")
  userRefreshToken: process.env.EBAY_USER_REFRESH_TOKEN // Optional: for 10k-50k req/day
};

const authClient = new EbayOAuthClient(config);

// Get access token (automatically authenticates if needed)
try {
  // Attempts user token first (10k-50k req/day), falls back to client credentials (1k req/day)
  const token = await authClient.getAccessToken();
  console.log('Access token:', token);

  // Check authentication status
  const isAuth = authClient.isAuthenticated();
  console.log('Is authenticated:', isAuth);

  // Check if using user tokens
  const hasUserTokens = authClient.hasUserTokens();
  console.log('Using user tokens:', hasUserTokens);

  // Token is automatically cached until expiry (with 60-second buffer)
  // Subsequent calls return cached token
  const cachedToken = await authClient.getAccessToken();

  // Generate OAuth URL for user consent (to get user tokens)
  const oauthUrl = authClient.generateUserConsentUrl(['https://api.ebay.com/oauth/api_scope/sell.inventory']);
  console.log('OAuth URL:', oauthUrl);

  // Clear token manually if needed
  authClient.clearToken();
} catch (error) {
  console.error('Authentication failed:', error.message);
}

// Expected output:
// Access token: v^1.1#i^1#...
// Is authenticated: true
// Using user tokens: true

```

--------------------------------

### Initialize eBay API MCP Server (TypeScript)

Source: https://context7.com/yosefhayim/ebay-api-mcp-server/llms.txt

Initializes and runs the eBay MCP server, dynamically registering tools and handling OAuth authentication. It requires the MCP SDK and specific API definitions. The server listens on stdio for communication.

```typescript
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { EbaySellerApi } from "./api/index.js";
import { getEbayConfig } from "./config/environment.js";

// Initialize server
const server = new McpServer(
  {
    name: "ebay-api-mcp-server",
    version: "1.4.5",
  },
  {
    capabilities: {
      tools: {},
    },
  }
);

// Initialize eBay API client with config from environment
const config = getEbayConfig(); // Reads EBAY_CLIENT_ID, EBAY_CLIENT_SECRET, EBAY_ENVIRONMENT
const api = new EbaySellerApi(config);

// Initialize API (load tokens from storage)
await api.initialize();

// Register tools dynamically
const tools = getToolDefinitions();
for (const tool of tools) {
  server.registerTool(
    tool.name,
    {
      description: tool.description,
      inputSchema: tool.inputSchema,
    },
    async (args: Record<string, unknown>) => {
      const result = await executeTool(api, tool.name, args || {});
      return {
        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
      };
    }
  );
}

// Start server on stdio
const transport = new StdioServerTransport();
await server.connect(transport);
console.error("eBay API MCP Server running on stdio");

```

--------------------------------

### Manage eBay Marketing Campaigns and Promotions (TypeScript)

Source: https://context7.com/yosefhayim/ebay-api-mcp-server/llms.txt

This snippet demonstrates how to use the MarketingApi and RecommendationApi to retrieve active campaigns, promotions, and listing recommendations from the eBay API. It requires an initialized client and handles potential errors during API calls. The output includes details about campaigns and recommendations.

```typescript
import { MarketingApi } from './api/marketing-and-promotions/marketing.js';
import { RecommendationApi } from './api/marketing-and-promotions/recommendation.js';

const marketing = new MarketingApi(client);
const recommendation = new RecommendationApi(client);

try {
  // Get active campaigns
  const campaigns = await marketing.getCampaigns('RUNNING', 'EBAY_US', 50);
  console.log(`Active campaigns: ${campaigns.total}`);
  campaigns.campaigns?.forEach(campaign => {
    console.log(`Campaign: ${campaign.campaignName}`);
    console.log(`  Status: ${campaign.campaignStatus}`);
    console.log(`  Budget: ${campaign.budget?.value} ${campaign.budget?.currency}`);
  });

  // Get promotions
  const promotions = await marketing.getPromotions('EBAY_US', 50);
  console.log(`Promotions: ${promotions.total}`);

  // Get listing recommendations
  const recommendations = await recommendation.findListingRecommendations(
    { listingIds: ['110123456789', '110123456790'] },
    undefined,
    10,
    0,
    'EBAY_US'
  );

  console.log('Recommendations:', recommendations.total);
  recommendations.listingRecommendations?.forEach(rec => {
    console.log(`Listing ${rec.listingId}:`);
    rec.recommendations?.forEach(r => {
      console.log(`  - ${r.type}: ${r.message}`);
    });
  });

} catch (error) {
  console.error('Marketing operation failed:', error.message);
}
```

--------------------------------

### Configure MCP Server for eBay API (Claude Desktop)

Source: https://github.com/yosefhayim/ebay-api-mcp-server/blob/main/README.md

This JSON configuration is for setting up the eBay MCP server within Claude Desktop. It specifies the command to run the server and necessary environment variables for authentication and environment selection. Ensure you replace placeholder values with your actual eBay credentials.

```json
{
  "mcpServers": {
    "ebay": {
      "command": "npx",
      "args": ["-y", "ebay-mcp"],
      "env": {
        "EBAY_CLIENT_ID": "your_client_id",
        "EBAY_CLIENT_SECRET": "your_client_secret",
        "EBAY_ENVIRONMENT": "sandbox",
        "EBAY_REDIRECT_URI": "your_runame"
      }
    }
  }
}
```

--------------------------------

### eBay API Credentials Environment Variables (.env file)

Source: https://github.com/yosefhayim/ebay-api-mcp-server/blob/main/README.md

This bash script defines environment variables required for eBay API authentication. Create a `.env` file in your project root and populate it with your eBay credentials. It includes optional variables for refresh tokens to enable higher rate limits.

```bash
EBAY_CLIENT_ID=your_client_id
EBAY_CLIENT_SECRET=your_client_secret
EBAY_ENVIRONMENT=sandbox  # or "production"
EBAY_REDIRECT_URI=your_runame

# Optional: For higher rate limits (10k-50k req/day)
EBAY_USER_REFRESH_TOKEN=your_refresh_token
```

--------------------------------

### Run Diagnostic Tool in Bash

Source: https://github.com/yosefhayim/ebay-api-mcp-server/blob/main/README.md

Executes diagnostic commands for the eBay MCP server. The `npm run diagnose` command initiates interactive diagnostics, while `npm run diagnose:export` generates a diagnostic report.

```bash
# Interactive diagnostics
npm run diagnose

# Export diagnostic report
npm run diagnose:export
```

--------------------------------

### Inventory Management API

Source: https://context7.com/yosefhayim/ebay-api-mcp-server/llms.txt

Provides endpoints for creating, retrieving, and deleting inventory items. Supports managing product details, availability, and pricing.

```APIDOC
## Inventory Management API

### Description
Create and manage inventory items with product details, availability, and pricing.

### Method
POST, GET, DELETE

### Endpoint
- `POST /sell/inventory/v1/inventory_item`
- `GET /sell/inventory/v1/inventory_item`
- `GET /sell/inventory/v1/inventory_item/{sku}`
- `DELETE /sell/inventory/v1/inventory_item/{sku}`

### Parameters
#### Path Parameters
- **sku** (string) - Required - The unique identifier for the inventory item.

#### Query Parameters
- **limit** (number) - Optional - The maximum number of results to return for `getInventoryItems`.
- **offset** (number) - Optional - The number of results to skip for `getInventoryItems`.

#### Request Body (for `createOrReplaceInventoryItem`)
- **sku** (string) - Required - The SKU of the inventory item.
- **product** (object) - Required - Details about the product, including `title`, `description`, `aspects`, and `imageUrls`.
- **condition** (string) - Required - The condition of the item (e.g., 'NEW').
- **availability** (object) - Required - Information about item availability, such as `shipToLocationAvailability` with `quantity`.

### Request Example (Create or Replace Item)
```json
await inventory.createOrReplaceInventoryItem('SKU-LAPTOP-001', {
  product: {
    title: 'Dell XPS 15 Laptop',
    description: 'High-performance laptop with Intel i7 processor',
    aspects: {
      Brand: ['Dell'],
      Model: ['XPS 15'],
      'Processor Type': ['Intel Core i7']
    },
    imageUrls: ['https://example.com/laptop.jpg']
  },
  condition: 'NEW',
  availability: {
    shipToLocationAvailability: {
      quantity: 10
    }
  }
});
```

### Request Example (Get Items)
```json
const items = await inventory.getInventoryItems(25, 0);
```

### Request Example (Get Specific Item)
```json
const item = await inventory.getInventoryItem('SKU-LAPTOP-001');
```

### Request Example (Delete Item)
```json
await inventory.deleteInventoryItem('SKU-LAPTOP-001');
```

### Response
#### Success Response (200)
- **(object)** - Response varies based on the operation. `getInventoryItems` returns a paginated list, while `getInventoryItem` returns details for a single item.

#### Response Example (Get Items)
```json
{
  "total": 3,
  "inventoryItems": [
    { "sku": "SKU-LAPTOP-001", "product": { "title": "Dell XPS 15 Laptop" } },
    { "sku": "SKU-PHONE-001", "product": { "title": "iPhone 15 Pro" } },
    { "sku": "SKU-TABLET-001", "product": { "title": "iPad Pro 12.9" } }
  ]
}
```

#### Response Example (Get Specific Item)
```json
{
  "sku": "SKU-LAPTOP-001",
  "product": {
    "title": "Dell XPS 15 Laptop",
    "description": "High-performance laptop with Intel i7 processor",
    "aspects": {
      "Brand": ["Dell"],
      "Model": ["XPS 15"],
      "Processor Type": ["Intel Core i7"]
    },
    "imageUrls": ["https://example.com/laptop.jpg"]
  },
  "condition": "NEW",
  "availability": {
    "shipToLocationAvailability": {
      "quantity": 10
    }
  }
}
```
```

--------------------------------

### Retrieve Orders and Create Shipping Fulfillments

Source: https://context7.com/yosefhayim/ebay-api-mcp-server/llms.txt

Uses FulfillmentApi to query orders with status filters, retrieve order details, and create shipping fulfillments with tracking information. Supports pagination and includes buyer information, pricing details, and fulfillment status tracking.

```typescript
import { FulfillmentApi } from './api/order-management/fulfillment.js';
import { EbayApiClient } from './api/client.js';

const client = new EbayApiClient(config);
const fulfillment = new FulfillmentApi(client);

try {
  // Get orders with filters
  const orders = await fulfillment.getOrders(
    'orderfulfillmentstatus:{NOT_STARTED|IN_PROGRESS}',
    50,
    0
  );

  console.log(`Total orders: ${orders.total}`);
  orders.orders?.forEach(order => {
    console.log(`Order ${order.orderId}: ${order.orderFulfillmentStatus}`);
    console.log(`  Buyer: ${order.buyer?.username}`);
    console.log(`  Total: ${order.pricingSummary?.total?.value} ${order.pricingSummary?.total?.currency}`);
  });

  // Get specific order details
  const order = await fulfillment.getOrder('12-34567-89012');
  console.log('Order details:', order);

  // Create shipping fulfillment
  await fulfillment.createShippingFulfillment('12-34567-89012', {
    lineItems: [
      {
        lineItemId: '1234567890',
        quantity: 1
      }
    ],
    shippedDate: new Date().toISOString(),
    shippingCarrierCode: 'USPS',
    trackingNumber: '9400111899563824166592'
  });

  console.log('Fulfillment created successfully');

  // Get all fulfillments for an order
  const fulfillments = await fulfillment.getShippingFulfillments('12-34567-89012');
  console.log(`Fulfillments: ${fulfillments.total}`);

} catch (error) {
  console.error('Fulfillment operation failed:', error.message);
}
```

--------------------------------

### Run eBay MCP HTTP Server for Testing (TypeScript)

Source: https://context7.com/yosefhayim/ebay-api-mcp-server/llms.txt

This code sets up an Express.js server to run the eBay MCP in HTTP mode, facilitating testing with external tools. It uses middleware like cors and helmet for security and enables JSON request parsing. The server registers tool endpoints, allowing execution of eBay API functions via HTTP POST requests and provides an endpoint to list available tools.

```typescript
import express from 'express';
import cors from 'cors';
import helmet from 'helmet';
import { EbaySellerApi } from './api/index.js';
import { getEbayConfig } from './config/environment.js';
import { getToolDefinitions, executeTool } from './tools/index.js';

const app = express();
const api = new EbaySellerApi(getEbayConfig());

// Security and parsing middleware
app.use(helmet());
app.use(cors());
app.use(express.json());

// Initialize API
await api.initialize();

// Register tool endpoints
const tools = getToolDefinitions();
for (const tool of tools) {
  app.post(`/tools/${tool.name}`, async (req, res) => {
    try {
      const result = await executeTool(api, tool.name, req.body);
      res.json(result);
    } catch (error) {
      res.status(500).json({ error: error.message });
    }
  });
}

// List available tools
app.get('/tools', (req, res) => {
  res.json(tools.map(t => ({ name: t.name, description: t.description })));
});

app.listen(3000, () => {
  console.log('eBay MCP HTTP Server running on http://localhost:3000');
});

// Test with curl:
// curl -X POST http://localhost:3000/tools/ebay_get_inventory_items \
//   -H "Content-Type: application/json" \
//   -d '{"limit": 10}'
```

--------------------------------

### Create and Manage Inventory Items with eBay Inventory API

Source: https://context7.com/yosefhayim/ebay-api-mcp-server/llms.txt

Uses InventoryApi to create, retrieve, and delete inventory items with product details, aspects, and availability information. Supports pagination for retrieving multiple items and returns structured inventory data including SKU, product title, and quantity.

```typescript
import { InventoryApi } from './api/listing-management/inventory.js';
import { EbayApiClient } from './api/client.js';

const client = new EbayApiClient(config);
const inventory = new InventoryApi(client);

try {
  // Create or update inventory item
  await inventory.createOrReplaceInventoryItem('SKU-LAPTOP-001', {
    product: {
      title: 'Dell XPS 15 Laptop',
      description: 'High-performance laptop with Intel i7 processor',
      aspects: {
        Brand: ['Dell'],
        Model: ['XPS 15'],
        'Processor Type': ['Intel Core i7']
      },
      imageUrls: ['https://example.com/laptop.jpg']
    },
    condition: 'NEW',
    availability: {
      shipToLocationAvailability: {
        quantity: 10
      }
    }
  });

  // Get inventory items with pagination
  const items = await inventory.getInventoryItems(25, 0);
  console.log(`Total items: ${items.total}`);
  items.inventoryItems?.forEach(item => {
    console.log(`SKU: ${item.sku}, Title: ${item.product?.title}`);
  });

  // Get specific item
  const item = await inventory.getInventoryItem('SKU-LAPTOP-001');
  console.log('Item details:', item);

  // Delete item
  await inventory.deleteInventoryItem('SKU-LAPTOP-001');

} catch (error) {
  console.error('Inventory operation failed:', error.message);
}
```

--------------------------------

### Docker Compose Configuration with YAML

Source: https://context7.com/yosefhayim/ebay-api-mcp-server/llms.txt

Define eBay MCP Server Docker service configuration using docker-compose.yml with version 3.8. Configures service build, environment variables from .env file, port mapping (3000:3000), restart policy, and volume mounting for data persistence. Requires Docker Compose 3.8+.

```yaml
# docker-compose.yml
version: '3.8'
services:
  ebay-mcp:
    build: .
    env_file: .env
    ports:
      - "3000:3000"
    restart: unless-stopped
    volumes:
      - ./data:/app/data
```

--------------------------------

### Manage eBay Payment Disputes with TypeScript

Source: https://context7.com/yosefhayim/ebay-api-mcp-server/llms.txt

Manage payment disputes on eBay, including searching for open disputes, retrieving details, contesting, adding evidence, and accepting disputes. This snippet utilizes the DisputeApi from the provided client library.

```typescript
import { DisputeApi } from './api/order-management/dispute.js';
import { EbayApiClient } from './api/client.js';

const client = new EbayApiClient(config);
const dispute = new DisputeApi(client);

try {
  // Search for payment disputes
  const disputes = await dispute.getPaymentDisputeSummaries({
    payment_dispute_status: 'OPEN',
    limit: 50,
    offset: 0
  });

  console.log(`Open disputes: ${disputes.total}`);
  disputes.disputeSummaries?.forEach(summary => {
    console.log(`Dispute ${summary.paymentDisputeId}: ${summary.paymentDisputeStatus}`);
    console.log(`  Order: ${summary.orderId}`);
    console.log(`  Reason: ${summary.reason}`);
  });

  // Get specific dispute details
  const disputeDetails = await dispute.getPaymentDispute('dispute-12345');
  console.log('Dispute amount:', disputeDetails.monetaryTransactions?.[0].amountPaid?.value);

  // Get dispute activity history
  const activity = await dispute.getActivities('dispute-12345');
  console.log('Activity count:', activity.activity?.length);

  // Contest a dispute with evidence
  await dispute.contestPaymentDispute('dispute-12345', {
    returnAddress: {
      addressLine1: '123 Main St',
      city: 'San Jose',
      stateOrProvince: 'CA',
      postalCode: '95051',
      countryCode: 'US'
    },
    revision: 1
  });

  // Add evidence to dispute
  await dispute.addEvidence('dispute-12345', {
    evidenceType: 'PROOF_OF_DELIVERY',
    files: [{ fileId: 'file-123' }],
    lineItems: [{ itemId: 'item-456', quantity: 1 }]
  });

  // Accept a dispute
  await dispute.acceptPaymentDispute('dispute-12345', {
    returnAddress: {
      addressLine1: '123 Main St',
      city: 'San Jose',
      stateOrProvince: 'CA',
      postalCode: '95051',
      countryCode: 'US'
    },
    revision: 1
  });

} catch (error) {
  console.error('Dispute operation failed:', error.message);
}

```

--------------------------------

### Order Fulfillment API

Source: https://context7.com/yosefhayim/ebay-api-mcp-server/llms.txt

Enables retrieval of orders and creation of shipping fulfillments, including the ability to provide tracking information.

```APIDOC
## Order Fulfillment API

### Description
Retrieve orders and create shipping fulfillments with tracking information.

### Method
GET, POST

### Endpoint
- `GET /sell/fulfillment/v1/orders`
- `GET /sell/fulfillment/v1/orders/{orderId}`
- `POST /sell/fulfillment/v1/fulfillment`
- `GET /sell/fulfillment/v1/fulfillment` (to get fulfillments for an order)

### Parameters
#### Path Parameters
- **orderId** (string) - Required - The unique identifier for the order.

#### Query Parameters
- **filter** (string) - Optional - Filters for orders, e.g., `orderfulfillmentstatus:{NOT_STARTED|IN_PROGRESS}`.
- **limit** (number) - Optional - The maximum number of results to return.
- **offset** (number) - Optional - The number of results to skip.

#### Request Body (for `createShippingFulfillment`)
- **orderId** (string) - Required - The ID of the order to fulfill.
- **lineItems** (array) - Required - An array of objects, each specifying `lineItemId` and `quantity`.
- **shippedDate** (string) - Required - The date the shipment was made (ISO format).
- **shippingCarrierCode** (string) - Required - The code for the shipping carrier.
- **trackingNumber** (string) - Required - The tracking number for the shipment.

### Request Example (Get Orders)
```json
const orders = await fulfillment.getOrders('orderfulfillmentstatus:{NOT_STARTED|IN_PROGRESS}', 50, 0);
```

### Request Example (Get Specific Order)
```json
const order = await fulfillment.getOrder('12-34567-89012');
```

### Request Example (Create Shipping Fulfillment)
```json
await fulfillment.createShippingFulfillment('12-34567-89012', {
  lineItems: [
    {
      lineItemId: '1234567890',
      quantity: 1
    }
  ],
  shippedDate: new Date().toISOString(),
  shippingCarrierCode: 'USPS',
  trackingNumber: '9400111899563824166592'
});
```

### Request Example (Get Fulfillments for Order)
```json
const fulfillments = await fulfillment.getShippingFulfillments('12-34567-89012');
```

### Response
#### Success Response (200)
- **(object)** - Response varies based on the operation. `getOrders` returns a paginated list of orders, `getOrder` returns order details, and `createShippingFulfillment` confirms creation.

#### Response Example (Get Orders)
```json
{
  "total": 5,
  "orders": [
    {
      "orderId": "12-34567-89012",
      "orderFulfillmentStatus": "NOT_STARTED",
      "buyer": { "username": "testbuyer123" },
      "pricingSummary": { "total": { "value": "49.99", "currency": "USD" } }
    },
    {
      "orderId": "12-34567-89013",
      "orderFulfillmentStatus": "IN_PROGRESS",
      "buyer": { "username": "buyer456" },
      "pricingSummary": { "total": { "value": "29.99", "currency": "USD" } }
    }
  ]
}
```

#### Response Example (Get Specific Order)
```json
{
  "orderId": "12-34567-89012",
  "orderFulfillmentStatus": "NOT_STARTED",
  "buyer": { "username": "testbuyer123" },
  "pricingSummary": { "total": { "value": "49.99", "currency": "USD" } },
  // ... other order details
}
```

#### Response Example (Create Shipping Fulfillment)
```json
{
  "fulfillmentId": "some-fulfillment-id",
  "orderId": "12-34567-89012",
  "shippedDate": "2023-10-27T10:00:00.000Z",
  "shippingCarrierCode": "USPS",
  "trackingNumber": "9400111899563824166592",
  "lineItems": [
    { "lineItemId": "1234567890", "quantity": 1 }
  ]
}
```
```
Tokens:
Raw