<p align="center">
  <img src="https://capsule-render.vercel.app/api?type=waving&color=0:00a86b,100:0f766e&height=120&section=header&text=joongna-mcp&fontSize=42&fontColor=ffffff&animation=fadeIn" alt="joongna-mcp" />
</p>

<p align="center">
  <b>중고나라 매물 검색 · 상세 · 시세 요약</b><br/>
  <sub>Dynamically search Joongna listings in your MCP clients</sub>
</p>

<p align="center">
  <a href="https://github.com/iamkw0n/joongna-mcp/stargazers"><img src="https://img.shields.io/github/stars/iamkw0n/joongna-mcp?style=for-the-badge&logo=github&color=00a86b" alt="Stars"/></a>
  <a href="https://github.com/iamkw0n/joongna-mcp/network/members"><img src="https://img.shields.io/github/forks/iamkw0n/joongna-mcp?style=for-the-badge&logo=github&color=00a86b" alt="Forks"/></a>
  <a href="https://github.com/iamkw0n/joongna-mcp/issues"><img src="https://img.shields.io/github/issues/iamkw0n/joongna-mcp?style=for-the-badge&logo=github&color=00a86b" alt="Issues"/></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-00a86b?style=for-the-badge" alt="License"/></a>
</p>

<p align="center">
  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-stdio-0f766e?style=flat-square&logo=anthropic" alt="MCP"/></a>
  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-339933?style=flat-square&logo=node.js&logoColor=white" alt="Node"/></a>
  <a href="https://www.typescriptlang.org"><img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript"/></a>
  <a href="https://web.joongna.com"><img src="https://img.shields.io/badge/source-web.joongna.com-00a86b?style=flat-square" alt="Joongna"/></a>
</p>

<p align="center">
  <a href="#-quick-start">Quick Start</a>
  ·
  <a href="#-tools">Tools</a>
  ·
  <a href="#-client-setup">Client Setup</a>
  ·
  <a href="#-examples">Examples</a>
  ·
  <a href="#-faq">FAQ</a>
  ·
  <a href="https://github.com/iamkw0n/joongna-mcp/issues/new">Report Bug</a>
</p>

---

<details>
<summary><b>📑 Table of contents (Click to show)</b></summary>

- [Important Notices](#-important-notices)
- [Features](#-features)
- [Quick Start](#-quick-start)
- [Tools](#-tools)
- [One-Click Install Prompt](#-one-click-install-prompt)
- [Client Setup](#-client-setup)
  - [Cursor](#cursor)
  - [Claude Code](#claude-code)
  - [Claude Desktop](#claude-desktop)
  - [OpenAI Codex](#openai-codex)
  - [ChatGPT](#chatgpt)
- [Examples](#-examples)
- [How It Works](#-how-it-works)
- [FAQ](#-faq)
- [License](#-license)

</details>

---

## ⚠️ Important Notices

> [!IMPORTANT]
> 이 프로젝트는 **중고나라 공식 Open API가 아닌** 공개 웹 페이지를 파싱합니다. 사이트 구조가 바뀌면 일부 기능이 깨질 수 있습니다. **개인·비상업적 용도**를 권장합니다.

> [!WARNING]
> 과도한 요청은 중고나라에서 차단될 수 있습니다. 차단이 잦으면 `ZYTE_API_KEY` 환경 변수로 Zyte 프록시를 켤 수 있습니다.

---

## ✨ Features

| | |
| :--- | :--- |
| 🔍 **매물 검색** | 키워드·카테고리 기반 중고나라 검색 |
| 📦 **상세 조회** | 상품 상세 · 판매 정보 조회 |
| 📉 **시세 확인** | search-price 기반 시세 범위 · 추이 · 요약 |
| 🔌 **stdio MCP** | Cursor, Claude, Codex 등 로컬 클라이언트 지원 |
| 📦 **Zero setup** | `npm install` 후 `npm start`로 즉시 실행 |

---

## 🚀 Quick Start

```bash
git clone https://github.com/iamkw0n/joongna-mcp.git
cd joongna-mcp
npm install
npm start
```

공통 실행 명령:

```bash
node dist/index.js
```

---

## 🛠 Tools

| Tool | Description |
| :--- | :--- |
| `search_listings` | 키워드 매물 검색 |
| `get_listing_detail` | 상품 상세 · 판매 정보 |
| `get_market_price` | 시세 범위 · 최근 추이 |
| `summarize_search_market` | 검색 결과 기반 시세 요약 |
| `list_categories` | 카테고리 목록 |
| `proxy_status` | 프록시 상태 확인 |

---

## 💬 One-Click Install Prompt

Cursor / Claude Code / Codex에서 아래 프롬프트를 붙여넣으면 MCP 설치를 요청할 수 있습니다.

```
Github에서 iamkw0n/joongna-mcp 를 가져와서 MCP 서버 설치를 해줘.
```

---

## 🔧 Client Setup

| Client | Config file | stdio |
| :--- | :--- | :---: |
| Cursor | `.cursor/mcp.json` | ✅ |
| Claude Code | `.mcp.json` | ✅ |
| Claude Desktop | `claude_desktop_config.json` | ✅ |
| Codex | `.codex/config.toml` | ✅ |
| ChatGPT | Connector URL | ❌ |

### Cursor

프로젝트 루트에 `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "joongna-mcp": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "${workspaceFolder}"
    }
  }
}
```

### Claude Code

프로젝트 루트에 `.mcp.json`:

```json
{
  "mcpServers": {
    "joongna-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["./dist/index.js"]
    }
  }
}
```

CLI:

```bash
claude mcp add joongna-mcp -s project -- node ./dist/index.js
```

### Claude Desktop

macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`

Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "joongna-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/joongna-mcp/dist/index.js"],
      "cwd": "/absolute/path/to/joongna-mcp"
    }
  }
}
```

> [!WARNING]
> Claude Desktop은 `${workspaceFolder}`를 지원하지 않습니다. **절대 경로**를 사용하세요.

### OpenAI Codex

프로젝트 `.codex/config.toml` 또는 `~/.codex/config.toml`:

```toml
[mcp_servers.joongna-mcp]
command = "node"
args = ["./dist/index.js"]
cwd = "/absolute/path/to/joongna-mcp"
enabled = true
```

CLI:

```bash
codex mcp add joongna-mcp -- node ./dist/index.js
```

연결 확인: Codex 세션에서 `/mcp`

### ChatGPT

> [!IMPORTANT]
> ChatGPT 커넥터는 **HTTPS MCP 엔드포인트**만 지원합니다. 이 레포는 로컬 **stdio** 서버이므로 ChatGPT에 직접 연결할 수 없습니다.

---

## 💡 Examples

```
갤럭시북 중고나라 검색해줘
```

```
아이폰 15 최근 매물 찾아줘
```

```
229401708 상품 상세 보여줘
```

```
맥북 시세 요약해줘
```

```
노트북 카테고리 ID 찾아줘
```

```
프록시 상태 확인해줘
```

---

## ⚙️ How It Works

```mermaid
flowchart LR
    A[MCP Client] -->|stdio| B[joongna-mcp]
    B --> C[web.joongna.com/search]
    B --> D[web.joongna.com/product]
    B --> E[web.joongna.com/search-price]
    B --> F[api.zyte.com/v1/extract]
```

| Endpoint | Usage |
| :--- | :--- |
| `web.joongna.com/search` | 매물 검색 |
| `web.joongna.com/product` | 상품 상세 |
| `web.joongna.com/search-price` | 시세 조회 |
| `api.zyte.com/v1/extract` | 차단 대응용 프록시 |

## 📄 License

[MIT](./LICENSE) © iamkw0n

<p align="center">
  <sub>Built with ❤️ by <a href="https://github.com/iamkw0n">iamkw0n</a> · 중고나라와 공식적으로 관련이 없는 비공식 프로젝트입니다</sub>
</p>