# MCP Server

> Connect Claude, Cursor, VS Code, Manus or any MCP client to Easyparser Amazon data through the hosted MCP server or a local npx server.

Source: https://docs.easyparser.com/integrations/mcp-server

The Easyparser MCP server exposes the Real-Time API operations to AI agents as callable tools through the Model Context Protocol. You connect your MCP client to one endpoint, and your agent can fetch Amazon product, offer, search and seller data, monitor bulk jobs and check your credit balance without custom integration code. Coding agents can also use it to test requests while they build your integration (see [Build an integration with an AI coding agent](#build-an-integration-with-an-ai-coding-agent)).

The MCP server is a thin, read-only adapter over the [Real-Time API](/real-time-integration/overview). It calls the same operations, so credit costs, marketplaces and data shapes match the Real-Time API pages. This page covers connecting a client and what each tool does.

## Before you begin

You need an Easyparser API key. Sign up at https://app.easyparser.com/signup (the free plan includes 100 credits per month and needs no credit card), then copy your key from **Account > Plan** at https://app.easyparser.com/account/plan.

Wherever a setup step below shows `YOUR_API_KEY`, paste your key.

> **INFO:** The `list_operations` tool works without an API key, so an agent can explore the operation catalog before you sign up.

## Available tools

The server provides 18 tools. Data tools cost the same credits as the matching Real-Time API operation; monitoring and account tools are free. See [Credit Consumption](/essentials/credit-consumption) for the full rules.

- Each tool description tells the agent what the tool returns, when to use it, when a cheaper tool fits better, and what it costs.
- Every data tool response includes `success`, `operation`, `data`, `credits_used`, `credits_remaining` and `request_id`, so the agent can track its budget.
- Rate-limit and authentication errors come back as readable guidance instead of raw HTTP status codes.

### Product data

| Tool | Operation | Returns | Credits |
|---|---|---|---|
| `get_product_detail` | [`DETAIL`](/real-time-integration/detail) | Full product profile: title, brand, images, Buy Box price, rating, BSR, variants, top reviews | 1, or 2 with A+ content |
| `get_product_offers` | [`OFFER`](/real-time-integration/offer) | Seller offers: price, condition, FBA or FBM, seller rating, Buy Box winner | 1 per page, max 5 pages |
| `get_bestseller_rank` | [`BEST_SELLERS_RANK`](/real-time-integration/best-sellers-rank) | Current Best Sellers Rank by category | 1 |
| `get_package_dimensions` | [`PACKAGE_DIMENSION`](/real-time-integration/package-dimension) | Package dimensions, weight and Amazon fee category | 1 |
| `get_similar_products` | [`SIMILAR_PRODUCTS`](/real-time-integration/similar-products) | Similar products for an ASIN: title, brand, category, image | 1, 6 or 11 for 10, 50 or 100 results |
| `get_sales_history` | [`SALES_ANALYSIS_HISTORY`](/real-time-integration/sales-analysis-and-history) | Weekly trends for up to 12 months: views, sales, price, BSR | 5 plus 1 per month of history, max 17 |

### Search and discovery

| Tool | Operation | Returns | Credits |
|---|---|---|---|
| `search_products` | [`SEARCH`](/real-time-integration/search) | Keyword or search URL results with price, rating, Prime status and badges | 1 per page, max 5 pages |
| `lookup_product` | [`PRODUCT_LOOKUP`](/real-time-integration/product-lookup) | ASIN for a UPC, EAN, GTIN, ISBN, JAN or MINSAN code, with a product snapshot | 1 |

### Sellers

| Tool | Operation | Returns | Credits |
|---|---|---|---|
| `get_seller_profile` | [`SELLER_PROFILE`](/real-time-integration/seller-profile) | Legal business name, business address, feedback summary for the last 1, 3 and 12 months and all time | 1 |
| `get_seller_products` | [`SELLER_PRODUCTS`](/real-time-integration/seller-products) | A seller's catalog with brand, price, Prime status and ratings | 1 per page, max 5 pages |
| `get_seller_feedback` | [`SELLER_FEEDBACK`](/real-time-integration/seller-feedback) | Individual buyer feedback, filterable by rating and time period | 1 per page, max 5 pages |

### Bulk job monitoring

These tools track jobs you started with the [Bulk API](/bulk-integration/overview) or on the Bulk Requests page of the web app (https://app.easyparser.com/bulk-requests).

| Tool | Returns | Credits |
|---|---|---|
| `list_bulk_jobs` | Your bulk jobs with status and completed, failed and invalid counts | Free |
| `get_bulk_job_items` | Per-item outcomes inside a job, for debugging failed or invalid items | Free |
| `get_bulk_item_result` | The parsed data one item produced (kept for up to 24 hours) | Free |
| `get_bulk_webhook_logs` | Webhook delivery logs for your bulk items | Free |

### Error logs

| Tool | Returns | Credits |
|---|---|---|
| `get_error_logs` | Real-Time API and Bulk API request errors: error code, channel, operation, request parameters, timestamp | Free |

`get_error_logs` returns the same data as the Errors page of the web app (https://app.easyparser.com/errors).

### Account

| Tool | Returns | Credits |
|---|---|---|
| `list_operations` | Operation catalog with parameters, credit costs and supported domains. Works without an API key | Free |
| `check_credits` | Plan, credits used and remaining, reset date, per-minute credit limits, address usage, daily usage this month | Free |

### Prompts and resources

Clients that support MCP prompts can start these workflows in one step:

| Prompt | What it does |
|---|---|
| `analyze_competitor_product` | Listing details, seller offers and 3-month sales and BSR trends for one ASIN |
| `estimate_fba_logistics` | Package dimensions, weight and fee category for FBA planning |
| `match_barcodes_to_asins` | Converts a list of UPC, EAN, GTIN or ISBN codes into ASINs |
| `vet_amazon_seller` | Legal identity, reputation trend and negative feedback for a seller |
| `product_market_research` | Top organic results and demand comparison for a keyword niche |

The server also provides free, read-only resources that work without an API key:

| Resource | Contents |
|---|---|
| `easyparser://operations` | Every operation with its credit cost |
| `easyparser://marketplaces` | The Amazon domains the MCP server accepts |
| `easyparser://guide` | Rules for picking tools and saving credits |

## Connect your client

You can connect in two ways:

| Option | Endpoint or command | Use it when |
|---|---|---|
| Hosted remote server | `https://mcp.easyparser.com/mcp` | Your client supports remote (HTTP) MCP servers. No install needed. |
| Local server | `npx -y easyparser-mcp` | Your client supports only local stdio servers, or you want to run the server yourself. |

All hosted setups use the same endpoint, `https://mcp.easyparser.com/mcp`, and send your key in the `Authorization: Bearer YOUR_API_KEY` header.

> **WARNING:** `Authorization: Bearer` works only for the MCP server. The REST APIs use the `api_key` query parameter (Real-Time API, Account API) or the `api-key` header (Bulk API, Data Service).

### Cursor

The [GitHub repository](https://github.com/easyparser-com/mcp-easyparser) has one-click install links for the remote server and the local (npx) server. They open Cursor with the configuration filled in; replace `YOUR_API_KEY` when prompted.

To add the server manually, edit `.cursor/mcp.json`:

**.cursor/mcp.json**

```json
{
  "mcpServers": {
    "easyparser": {
      "type": "http",
      "url": "https://mcp.easyparser.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

### VS Code

The [GitHub repository](https://github.com/easyparser-com/mcp-easyparser) has a one-click install link for the remote server. VS Code then asks for your API key in an input prompt.

To add the server manually, edit `.vscode/mcp.json`:

**.vscode/mcp.json**

```json
{
  "servers": {
    "easyparser": {
      "type": "http",
      "url": "https://mcp.easyparser.com/mcp",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}
```

### Claude Code

Run this command in your terminal:

```bash
claude mcp add --scope user --transport http easyparser https://mcp.easyparser.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"
```

### Claude Desktop and claude.ai

Add the server as a custom connector:

### Step 1: Open the connector form

Go to **Settings > Connectors > Add > Add custom connector**.

### Step 2: Enter the server details

Set **Name** to `Easyparser` and **Remote MCP server URL** to `https://mcp.easyparser.com/mcp`, then click **Continue**.

### Step 3: Set authentication

Under **Authentication**, select **None**. Easyparser uses an API key, not OAuth.

### Step 4: Add the API key header

Under **Request headers**, add a header named `authorization` with the value `Bearer YOUR_API_KEY` and mark it **Required**. Click **Add**.

### Manus

Go to **Settings > Integrations > Custom MCP Servers > Add Server** and fill in the form:

| Field | Value |
|---|---|
| Server name | `Easyparser` |
| Transport type | `HTTP` |
| Server URL | `https://mcp.easyparser.com/mcp` |
| Custom headers | Name `Authorization`, value `Bearer YOUR_API_KEY` |

Click **Test** to check the connection, then **Save**.

### Any other MCP client

The hosted endpoint uses the [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http) transport at `https://mcp.easyparser.com/mcp`. Send your key in one of these headers:

| Header | Value |
|---|---|
| `Authorization` | `Bearer YOUR_API_KEY` (recommended) |
| `x-api-key` | `YOUR_API_KEY` |
| `api-key` | `YOUR_API_KEY` |
| `apikey` | `YOUR_API_KEY` |

### Local stdio server

For clients that only run local servers, start the npm package `easyparser-mcp` with your key in the `EASYPARSER_API_KEY` environment variable. A typical client configuration:

**mcp.json**

```json
{
  "mcpServers": {
    "easyparser": {
      "command": "npx",
      "args": ["-y", "easyparser-mcp"],
      "env": { "EASYPARSER_API_KEY": "YOUR_API_KEY" }
    }
  }
}
```

The package needs Node.js 18 or later.

## Self-host the HTTP server

You can run the HTTP server on your own infrastructure. Install the package globally and start `easyparser-mcp-http`:

```bash
npm install -g easyparser-mcp
PORT=3000 easyparser-mcp-http
```

In PowerShell, set the port with `$env:PORT="3000"; easyparser-mcp-http`. `PORT` defaults to `3000`. From a clone of the [repository](https://github.com/easyparser-com/mcp-easyparser), you can also run `node dist/http.js` or build the Docker image:

```bash
docker build -t easyparser-mcp .
docker run -p 3000:3000 easyparser-mcp
```

The server exposes these endpoints:

| Endpoint | Purpose |
|---|---|
| `POST /mcp` | MCP endpoint (Streamable HTTP) |
| `GET /health` | Health check |

Clients authenticate with the same headers as the hosted server. If a request has no key header, the server falls back to the `EASYPARSER_API_KEY` environment variable.

## Using it in requests

After you connect, ask your agent in plain language. The agent picks the tools, and each call is charged like the matching Real-Time API request.

![Animation: a question about the price and rating of an ASIN, the agent calls the Easyparser get_product_detail tool for 1 credit and answers with the price and rating](https://docs.easyparser.com/media/animations/docs-mcp-server-chat.jpg)

*Animation: a question about the price and rating of an ASIN, the agent calls the Easyparser get_product_detail tool for 1 credit and answers with the price and rating* ([MP4](https://docs.easyparser.com/media/animations/docs-mcp-server-chat.mp4))

```
What is the current price and rating of ASIN B0F25371FH?
```

```
Find the ASIN for UPC 041604458187, then show me its 6-month sales trend.
```

```
Who is the seller behind this product, what is their legal business name,
and what do their negative reviews say?
```

```
Compare the top 10 organic results for "stainless steel water bottle" on
amazon.de: prices, ratings, and which ones are Prime.
```

```
Is the bulk job I started this morning finished? If any items failed,
tell me which ASINs and why.
```

> **DANGER:** Agents can chain several paid tools for one prompt (for example, a lookup followed by a sales history call). Ask the agent to run `check_credits` first, or watch `credits_remaining` in tool responses, to keep usage under control.

## Build an integration with an AI coding agent

The MCP server also helps while you write code. When your coding agent (for example Claude Code, Cursor or an agent in VS Code) has the Easyparser MCP server connected, it can call the operations you plan to use, read real responses, and then write your integration against the actual field names. It can run your tests and fix mismatches before you review the code.

![Animation: a developer asks a coding agent to add Easyparser prices to an app; the agent calls list_operations and get_product_detail through MCP, writes a getPrice function that calls the Real-Time API and runs a passing test](https://docs.easyparser.com/media/animations/docs-mcp-server-coding-agent.jpg)

*Animation: a developer asks a coding agent to add Easyparser prices to an app; the agent calls list_operations and get_product_detail through MCP, writes a getPrice function that calls the Real-Time API and runs a passing test* ([MP4](https://docs.easyparser.com/media/animations/docs-mcp-server-coding-agent.mp4))

### Step 1: Connect the MCP server in your coding agent

Add the server as described in [Connect your client](#connect-your-client), for example with `claude mcp add` for Claude Code. Give your application its own key in an environment variable, such as `EASYPARSER_API_KEY`, instead of pasting the key into code.

### Step 2: Describe the task and ask the agent to test first

Name the data you need and tell the agent to try the request through MCP before it writes code:

```
Add current Amazon prices from Easyparser to my app. Use the Easyparser MCP
server to test a DETAIL request for ASIN B0CJB6V2L5 on amazon.com first, then
write a getPrice(asin) function that calls the Real-Time API with the key in
EASYPARSER_API_KEY, and add a test with a mocked API response.
```

### Step 3: Let the agent explore, then write the code

The agent usually calls `list_operations` (free) to choose the operation and its parameters, then one paid tool, for example `get_product_detail` (1 credit), to see a real response. It then writes code that calls `https://realtime.easyparser.com/v1/request` directly with field paths such as `result.detail.buybox_winner.price.value`, and runs your tests.

> **INFO:** MCP tool results contain the API response's `result` object (returned as `data`) plus the credit fields. Your application receives the full Real-Time API response, with `request_info`, `request_parameters`, `request_metadata` and `result` (see the [response envelope](/real-time-integration/overview#response-envelope)). Ask the agent to read the data from `result` and to check `request_info.success` in your code.

> **WARNING:** Every paid tool call the agent makes while testing uses credits. Ask it to run `check_credits` first, and mock the API in your automated tests so a test run does not send paid requests.

## Limitations

These are limits of the MCP tools, not of the API. Use the [Real-Time API](/real-time-integration/overview) directly when you need the full parameter set.

- The server is read-only. It cannot create bulk jobs, manage addresses or change your account.
- `get_product_offers`, `search_products`, `get_seller_products` and `get_seller_feedback` cap `max_page` at `5` (`min_page` and `max_page` both default to `1`), so a call can never reach page 6 or later. The Real-Time API accepts later page windows of up to 5 pages.
- `get_product_offers` accepts one `condition` filter per call. The Real-Time API lets you combine several condition flags.
- `get_seller_feedback` takes a `seller_id` only. The Real-Time API also accepts a seller URL.
- The tools do not expose `address_id`, the inline address fields (`zip_code`, `city`, `district`, `country_code`), `parameters` or `cookie`, so you cannot request address-specific results through MCP.
- `get_bulk_item_result` returns results for up to 24 hours. Results can be removed earlier.
- The marketplace list the MCP server accepts may differ from the list in [Supported Marketplaces](/essentials/supported-marketplaces). Read the `easyparser://marketplaces` resource for the exact list.

## Related

- [Real-Time API overview](/real-time-integration/overview)
- [Credit Consumption](/essentials/credit-consumption)
- [Supported Marketplaces](/essentials/supported-marketplaces)
- [Bulk API overview](/bulk-integration/overview)
- [Account API](/account/account-api)
- [n8n](/integrations/n8n)