ttbkk-mcp-server/README.md

MCP server providing access to Korean tteokbokki restaurant database with search, location-based queries, and brand information

# ttbkk-mcp-server

A Model Context Protocol (MCP) server that provides access to a comprehensive Korean tteokbokki (rice cake) restaurant database. Get real-time information about 4,600+ tteokbokki restaurants across Korea, including franchise locations, detailed restaurant information, and location-based searches.

## Features

- 🔍 **Restaurant Search**: Search by name, address, or brand
- 📍 **Location-based Queries**: Find restaurants within specific areas or radius
- 🏢 **Brand Information**: Access data for 21+ tteokbokki franchise brands
- 📊 **Real-time Statistics**: Live database statistics and restaurant counts
- 🗺️ **Geographic Queries**: Bounding box and proximity-based searches

## Quick Start

### Installation

```bash
npx ttbkk-mcp-server
```

### MCP Client Setup

Add to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "ttbkk": {
      "command": "npx",
      "args": ["-y", "ttbkk-mcp-server"]
    }
  }
}
```

For Claude Desktop, add this to your `claude_desktop_config.json`:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

## Available Tools

### Restaurant Search
- `search_tteokbokki_restaurants` - Search restaurants by name, address, or brand
- `get_restaurants_in_area` - Get restaurants within a bounding box
- `get_nearby_restaurants` - Find restaurants near coordinates with distance

### Restaurant Details
- `get_restaurant_details` - Get detailed information including brand and tags

### Brand Management
- `get_brand_list` - List all brands sorted by restaurant count
- `get_brand_details` - Get specific brand information
- `search_brands` - Search brands by name

## Resources

- `ttbkk://franchise-types` - List of 19 supported franchise brands with Korean names
- `ttbkk://database-statistics` - Real-time database statistics

## Database Coverage

- **4,600+ restaurants** across Korea
- **21 franchise brands** including 신전떡볶이, 동대문엽기떡볶이, 명랑핫도그, 청년다방, 배떡
- **19 franchise types** with Korean names
- **Real-time data** from live production database

## Requirements

- Node.js >= 18.0.0
- MCP-compatible client (Claude Desktop, etc.)

## Example Usage

After setup, you can ask your AI assistant:

- "Find tteokbokki restaurants in Gangnam"
- "What are the top tteokbokki franchise brands?"
- "Show me restaurants near Seoul Station"
- "Get details for a specific restaurant"

## Data Source

This server connects to the same production database used by the ttbkk-web application, providing access to real, up-to-date tteokbokki restaurant information collected by automated crawlers.

## License

MIT

## Related Projects

- [ttbkk-web](https://github.com/ttbkk/ttbkk-web) - React frontend using the same database
- [ttbkk-server](https://github.com/ttbkk/ttbkk-server) - Django crawler collecting restaurant data