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

<p align="center">
  <b>당근마켓 매물 검색 · 상세 · 시세 요약</b><br/>
  <sub>Dynamically search Daangn listings in your MCP clients</sub>
</p>

<p align="center">
  <a href="https://github.com/iamkw0n/danggn-mcp/stargazers"><img src="https://img.shields.io/github/stars/iamkw0n/danggn-mcp?style=for-the-badge&logo=github&color=ff6f0f" alt="Stars"/></a>
  <a href="https://github.com/iamkw0n/danggn-mcp/network/members"><img src="https://img.shields.io/github/forks/iamkw0n/danggn-mcp?style=for-the-badge&logo=github&color=ff6f0f" alt="Forks"/></a>
  <a href="https://github.com/iamkw0n/danggn-mcp/issues"><img src="https://img.shields.io/github/issues/iamkw0n/danggn-mcp?style=for-the-badge&logo=github&color=ff6f0f" alt="Issues"/></a>
  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-ff6f0f?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-ff8a3d?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://www.daangn.com"><img src="https://img.shields.io/badge/source-www.daangn.com-ff6f0f?style=flat-square" alt="Daangn"/></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/danggn-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

| 기능 | 설명 |
| :--- | :--- |
| 🔍 **매물 검색** | 키워드·동네 슬러그 기반 당근마켓 검색 |
| 📦 **상세 조회** | 게시글 상세 · 판매자 · 매너온도 조회 |
| 📉 **시세 확인** | 검색 결과 기반 가격 범위 · 요약 |
| 📍 **동네 슬러그** | 인근 동네 목록 · 슬러그 유효성 확인 |
| 🔌 **stdio MCP** | Cursor, Claude, Codex 등 로컬 클라이언트 지원 |
| 📦 **Zero setup** | `npm install` 후 `npm start`로 즉시 실행 |

---

## 🚀 Quick Start

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

공통 실행 명령:

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

---

## 🛠 Tools

| Tool | Description |
| :--- | :--- |
| `search_listings` | 키워드 매물 검색 |
| `get_listing_detail` | 게시글 상세 · 판매 정보 |
| `summarize_search_market` | 검색 결과 기반 시세 요약 |
| `list_nearby_regions` | 인근 동네 슬러그 목록 |
| `validate_region_slug` | 동네 슬러그 유효성 확인 |
| `proxy_status` | 프록시 상태 확인 |

---

## 💬 One-Click Install Prompt

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

```
Github에서 iamkw0n/danggn-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": {
    "danggn-mcp": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "${workspaceFolder}"
    }
  }
}
```

### Claude Code

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

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

CLI:

```bash
claude mcp add danggn-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": {
    "danggn-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/danggn-mcp/dist/index.js"],
      "cwd": "/absolute/path/to/danggn-mcp"
    }
  }
}
```

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

### OpenAI Codex

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

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

CLI:

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

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

### ChatGPT

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

---

## 💡 Examples

```
갤럭시북 당근마켓 검색해줘
```

```
아이폰 15 강남구 근처 당근 매물 찾아줘
```

```
iamkw0n 게시글 상세 보여줘
```

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

```
역삼동 동네 슬러그 찾아줘
```

```
강남구-386 슬러그 유효한지 확인해줘
```

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

---

## ⚙️ How It Works

```mermaid
flowchart LR
    A[MCP Client] -->|stdio| B[danggn-mcp]
    B --> C[www.daangn.com/kr/buy-sell]
    B --> D[fleamarketArticles JSON]
    B --> E[JSON-LD Product/ItemList]
    B --> F[api.zyte.com/v1/extract]
```

| Endpoint | Usage |
| :--- | :--- |
| `www.daangn.com/kr/buy-sell` | 매물 검색 |
| `www.daangn.com/kr/buy-sell/{articleId}` | 게시글 상세 |
| `fleamarketArticles` | 검색 결과 임베디드 JSON |
| `api.zyte.com/v1/extract` | 차단 대응용 프록시 |

### 동네 슬러그 형식

검색 범위를 좁히려면 `regionSlug`에 `동네이름-숫자ID` 형식을 사용하세요.

예: `강남구-386`, `역삼동-6035`

`list_nearby_regions`로 기본 페이지에 노출되는 인근 동네를 확인할 수 있습니다.

---

## 📄 License

[MIT](./LICENSE) © iamkw0n

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