# korea-data-mcp

<!-- mcp-name: io.github.parkseokjune/korea-data-mcp -->

**Korean-native in → clean English JSON out.**

An [MCP](https://modelcontextprotocol.io) server that gives AI agents direct access to
Korean-platform data through the [`kdatafactory`](https://apify.com/kdatafactory) Apify
actors. These are targets Westerners generally can't crawl — Korean-language UIs plus
aggressive anti-bot — wrapped as agent-callable tools that return clean English JSON.

## What it does

Each tool calls one Apify actor's `run-sync-get-dataset-items` endpoint and returns the
parsed list of dataset items. Runs are synchronous and can take 1–3 minutes.

## Tools

| Tool | Actor | Returns |
|------|-------|---------|
| `encar_listings` | `encar-scraper` | Korean used cars from Encar (~200,000 listings): `make_en`, `model_group_en` (Sonata, Grandeur, 5-Series), year, KRW price, mileage, `fuel_en`, `region_en`. Optional VIN and spec. |
| `kbchachacha_listings` | `kbchachacha-scraper` | Korean used cars from KB Chachacha, same English fields. |
| `passo_motorcycles` | `passo-scraper` | Korean used motorcycles from Passo (~11,000 listings), filterable by brand, year and price range. |
| `oliveyoung_rankings` | `oliveyoung-scraper` | Olive Young K-beauty best-sellers (overall or by category) and search, USD prices. |
| `hwahae_reviews` | `hwahae-scraper` | Hwahae K-beauty rankings, ratings and review counts. |
| `glowpick_rankings` | `glowpick-scraper` | Glowpick K-beauty rankings and ratings. |
| `naver_place` | `naver-place-scraper` | Korean local businesses from Naver Place (name, category, phone, address, hours, rating, reviews). |
| `naver_shopping_best` | `naver-shopping-best-scraper` | Naver Shopping best-seller rankings. |
| `danawa_prices` | `danawa-scraper` | Lowest prices and specs from Danawa, Korea's largest price-comparison site, for any keyword. |
| `wadiz_campaigns` | `wadiz-scraper` | Wadiz reward-crowdfunding campaigns: amount raised, funding rate, status. |
| `kream_prices` | `kream-ranking-scraper` | KREAM sneaker, streetwear and luxury resale rankings and prices. |
| `musinsa_rankings` | `musinsa-scraper` | Musinsa fashion rankings and products. |
| `kurly_products` | `kurly-scraper` | Market Kurly grocery prices, rankings and search. |

Each actor is billed per result returned (a few dollars per 1,000 rows) to the Apify account
whose token you set, so keep `maxItems` small for interactive use. Apify's free plan includes
$5 of monthly credit.

## Requirements

- Python ≥ 3.10
- An Apify API token — get one at <https://console.apify.com/account/integrations>

Set it in your environment before running:

```bash
export APIFY_TOKEN="apify_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
```

If `APIFY_TOKEN` is not set, every tool raises a clear error telling you to set it.

## Install & run

Run directly with [uvx](https://docs.astral.sh/uv/) (no install needed):

```bash
APIFY_TOKEN="apify_api_..." uvx korea-data-mcp
```

Or install with pip:

```bash
pip install korea-data-mcp
korea-data-mcp
```

The server speaks MCP over stdio.

## Claude Desktop configuration

Add this to your `claude_desktop_config.json`
(macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "korea-data": {
      "command": "korea-data-mcp",
      "env": {
        "APIFY_TOKEN": "apify_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

Or, using `uvx` so there's nothing to install first:

```json
{
  "mcpServers": {
    "korea-data": {
      "command": "uvx",
      "args": ["korea-data-mcp"],
      "env": {
        "APIFY_TOKEN": "apify_api_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

Restart Claude Desktop, and the thirteen Korean-data tools appear.

## Changes

**0.2.0**
- Fixed: every tool reported an error even on success (Apify's sync endpoint answers 201,
  and 0.1.x accepted only 200).
- Fixed: fresh installs crashed because `mcp` 2.x renamed `FastMCP`; `mcp` is now pinned below 2.
- Security: the Apify token now goes in the Authorization header, not the URL, so it no
  longer appears in MCP client logs.
- New tools: `kbchachacha_listings`, `passo_motorcycles`, `danawa_prices`, `wadiz_campaigns`.
  `encar_listings` returns English model family, fuel and region and takes `salesOnly` and
  `includeVinSpec`. Removed `kpop_photocard` (its source now blocks automated access).

## License

MIT