hotpepper_mcp

# hotpepper_mcp [https://zenn.dev/articles/6d6852f6ee43e3/edit](https://zenn.dev/akito1212/articles/6d6852f6ee43e3) A project to publish the HotPepper Gourmet API as an MCP (Model Context Protocol) server. AI agents such as Claude can search for restaurants and retrieve master data. Optional integration with Google Places API to automatically add ratings, reviews, and business hours. ## API Key Acquisition ### HotPepper Gourmet API (required) 1. Access [Recruit Web Service](https://webservice.recruit.co.jp/) 2. Create an account from "New Registration" 3. After logging in, apply for the **HotPepper Gourmet Search API** from "API Key Application" 4. Set the issued API key to `.env` as `HOTPEPPER_API_KEY` > Free usage available. Daily request limit (usually 1,000 requests/day). ### Google Places API (optional) 1. Create a project in [Google Cloud Console](https://console.cloud.google.com/) 2. Enable the following from "API and services" -> "Library" - **Places API** 3. Create credentials from "API and services" -> "Credentials" -> "Create credentials" -> "API key" 4. Set the issued API key to `.env` as `GOOGLE_PLACES_API_KEY` > If not set, Google Places integration will be skipped and only HotPepper information will be returned. > Google Places API is pay-per-use. Free tier available (monthly $200 credit). ## Setup ```bash cp .env.example .env # Edit .env to set API keys docker compose up --build ``` ## Architecture ``` Claude (MCP Client) │ MCP over HTTP (SSE) ▼ ┌─────────────────────────────────┐ │ MCP Server (FastAPI) │ │ app/main.py │ │ │ │ Tools: │ │ ・search_restaurants │ │ ・search_shops │ │ ・get_genres / get_budgets │ │ ・get_*_areas │ │ ・get_restaurant_reviews │ └──────────┬──────────────────────┘ │ ┌─────┴──────┐ ▼ ▼ HotPepper Google Places API Gourmet API (optional / enrich) ``` ### Data Flow (for `search_restaurants`) ``` 1. Claude → MCP Server: search_restaurants(keyword, lat, lng, ...) 2. MCP Server → HotPepper API: /gourmet/v1/?keyword=...&format=json 3. HotPepper API → MCP Server: Restaurant list 4. (If GOOGLE_PLACES_API_KEY is set) MCP Server → Google Places Text Search: Restaurant name + address Google Places → MCP Server: place_id MCP Server → Google Places Details: place_id Google Places → MCP Server: rating, reviews, opening_hours 5. MCP Server → Claude: Restaurant list (+ google_place fields) ``` ### Directory Structure ``` . ├── app/ │ ├── main.py # FastAPI + MCP Server definition │ ├── client.py # HotPepper API client │ ├── models.py # Pydantic models │ ├── googleplace/ │ │ ├── client.py # Google Places HTTP client │ │ └── enricher.py # Enrich HotPepper results with Google info │ └── tools/ # MCP tool implementation ├── tests/ ├── Dockerfile ├── docker-compose.yml └── pyproject.toml ``` ## Commands | Command | Description | |---------|------------| | `docker compose up --build` | Build and start MCP Server | | `docker compose down` | Stop and remove containers | | `docker compose logs -f` | Display logs in real-time | | `docker compose --profile test run --rm test` | Run tests |