Alko MCP

🚀 Alko MCP Server

このサーバーは、Model Context Protocol (MCP) を用いた本格的なサーバーで、AIアシスタントに Alko.fi のアルコール商品カタログへのアクセスを提供します。

✨ 主な機能

• 商品検索：11,900以上の商品を、名前、種類、産地国、価格帯、アルコール度数などで検索できます。
• 商品詳細：豊富なデータ（味のプロファイル、食事との相性、証明書、提供方法の提案など）を含む詳細情報を取得できます。
• Vivino評価：名前またはURLでVivino.comのワイン評価を取得できます。
• 店舗営業時間：「現在営業中」のフィルターを使って店舗の開店時間を確認できます。
• 店舗在庫状況：Alko店舗のリアルタイムの在庫状況を確認できます（ウェブスクレイピングによる）。
• 商品推薦：食事との相性、シーン、好みに基づいた商品推薦を取得できます。
• 店舗一覧：都市別に360以上のAlko店舗を閲覧できます。

すべてのツールは、LLMのトークン使用を効率的にするためにコンパクトなJSONを返します。

🎥 デモ

Claude Desktopを使って、Alko MCPで商品を検索し、在庫状況を確認し、推薦を取得する様子。

🛠️ MCPツール

🚀 クイックスタート

前提条件

• Node.js 24以上
• Google Cloud Firestore（ローカル開発用のエミュレーターも可）
• Playwright（ウェブスクレイピング用、自動インストールされます）

インストール

# リポジトリをクローン
git clone https://github.com/yourusername/alko-mcp.git
cd alko-mcp

# 依存関係をインストール
npm install

# Playwrightブラウザをインストール
npx playwright install chromium

# ビルド
npm run build

Firestoreエミュレーターを使ったローカル開発

ステップ1: Firestoreエミュレーターを起動（バックグラウンドで実行し続けます）

gcloud emulators firestore start --host-port=localhost:8081

ステップ2: Claude Desktop（または他のAIアシスタント）を起動

エミュレーターが空の場合、MCPサーバーは最初のクエリで自動的にバンドルされたシードデータ（約12,000の商品、約360の店舗）を読み込みます。手動での同期は必要ありません！

⚠️ 重要提示

エミュレーターはデータを保持しません。エミュレーターを再起動した後、最初の使用時にシードデータが再度自動的に読み込まれます。

オプション: 最新データの同期

Alko.fiから最新の商品データが必要な場合は、以下のコマンドを実行します。

export FIRESTORE_EMULATOR_HOST=localhost:8081

# Excelから最新の商品を同期（約30秒）
npm run sync-data

# ウェブサイトから最新の店舗を同期（約2分）
npm run sync-stores

# シードファイルにエクスポート（チームと共有するため）
npm run export-seed

🤖 AIアシスタントの設定

Claude Desktop

設定ファイル: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

ローカル開発用

{
  "mcpServers": {
    "alko": {
      "command": "node",
      "args": ["/absolute/path/to/alko-mcp/dist/server.js"],
      "env": {
        "FIRESTORE_EMULATOR_HOST": "localhost:8081"
      }
    }
  }
}

本番環境（Cloud Run）

{
  "mcpServers": {
    "alko": {
      "url": "https://YOUR-CLOUD-RUN-URL.run.app/mcp",
      "transport": "streamable-http"
    }
  }
}

ChatGPT Desktop

設定ファイル: ~/.config/chatgpt/mcp.json (macOS/Linux) または %APPDATA%\chatgpt\mcp.json (Windows)

ローカル開発用

{
  "servers": {
    "alko": {
      "command": "node",
      "args": ["/absolute/path/to/alko-mcp/dist/server.js"],
      "env": {
        "FIRESTORE_EMULATOR_HOST": "localhost:8081"
      }
    }
  }
}

本番環境（Cloud Run）

{
  "servers": {
    "alko": {
      "url": "https://YOUR-CLOUD-RUN-URL.run.app/mcp",
      "transport": "streamable-http"
    }
  }
}

Google Gemini (AI Studio)

Geminiでは、HTTPトランスポートを使用します。以下のコマンドでサーバーを起動します。

MCP_TRANSPORT=http PORT=3000 node dist/server.js

その後、AI StudioでMCPエンドポイントURLを設定します。

http://localhost:3000/mcp

本番環境では、APIトークン認証を使用してCloud Runにデプロイします（以下を参照）。

Claude Code CLI

プロジェクトの .mcp.json に以下を追加します。

{
  "mcpServers": {
    "alko": {
      "command": "node",
      "args": ["./dist/server.js"],
      "env": {
        "FIRESTORE_EMULATOR_HOST": "localhost:8081"
      }
    }
  }
}

💡 サンプルプロンプト

🔍 基本検索

Etsi minulle hyviä italialaisia punaviinejä alle 20 euroa

20ユーロ未満のイタリア産赤ワインを検索します。

🍷 ワイン推薦

Suosittele viiniä grillatulle lohelle. Budjetti noin 15-25 euroa.

予算15 - 25ユーロで、焼き鮭に合うワインを推薦します。

🥂 シャンパンとスパークリングワイン

Mitä samppanjoita Alkossa on saatavilla? Näytä 5 parasta vaihtoehtoa.

Alkoで入手可能なシャンパンのオプションを5つ表示します。

🍺 クラフトビール検索

Etsi IPA-oluita Suomesta tai muista Pohjoismaista

北欧産のIPAビールを検索します。

📊 商品詳細

Kerro lisää tuotteesta numero 906458

商品番号906458の詳細情報（味のプロファイルを含む）を取得します。

🏪 店舗営業時間

Mitkä Alkon myymälät ovat auki nyt Helsingissä?

現在ヘルシンキで営業中のAlko店舗を一覧表示します。

📍 店舗在庫状況

Onko Barolo-viiniä saatavilla Helsingin myymälöissä?

ヘルシンキの店舗でBaroloワインの在庫状況を確認します。

🎁 贈り物推薦

Etsi lahjaideoita viininystävälle. Budjetti 50-100 euroa.

ワイン愛好家に贈る50 - 100ユーロのプレミアムな贈り物アイデアを検索します。

🧀 食事との相性（Alkoの公式相性データを使用）

Suosittele viiniä äyriäisille / Recommend wine for seafood

Alkoの食事シンボル検索を使用して、シーフードとの相性が公式にタグ付けされた商品を検索します。

Tarvitsen viinin juustolautaselle. Juustot: brie, manchego ja sinihomejuusto.

チーズプレートに合うワインを推薦します（「淡いチーズ」と「濃厚なチーズ」にマッチします）。

🌍 地域別検索

Hae espanjalaisia punaviinejä Rioja-alueelta

リオハ地域のスペイン産赤ワインを検索します。

💰 予算内ショッピング

Parhaat viinit alle 10 eurolla arki-iltoihin

平日の夕食に最適な10ユーロ未満のワインを検索します。

🍾 特別なシーン

Suosittele kuohuviiniä uudenvuoden juhliin 20 hengelle

20人用の新年パーティーに合うスパークリングワインを推薦します。

⭐ Vivino評価

Etsi punaviinejä 15-25€ ja tarkista niiden Vivino-arvostelut

15 - 25ユーロの赤ワインを検索し、そのVivino評価を確認します。

🏆 最高評価のワイン

Mikä on Alkon parhaiten arvioitu Barolo Vivinossa?

Alkoの中でVivinoで最も高評価のBaroloワインを検索します。

📈 ワイン比較

Vertaile näiden viinien Vivino-arvosanoja: Amarone, Brunello di Montalcino

高級なイタリア産ワインのVivino評価を比較します。

📇 データソース

商品カタログ

• ソース: Alkoの公開Excel価格表
• URL: https://www.alko.fi/INTERSHOP/static/WFS/Alko-OnlineShop-Site/-/Alko-OnlineShop/fi_FI/Alkon%20Hinnasto%20Tekstitiedostona/alkon-hinnasto-tekstitiedostona.xlsx
• 商品数: 約11,900
• 更新方法: npm run sync-data を実行

店舗データ

• ソース: alko.fiの店舗検索からスクレイピング
• 店舗数: 約360
• 含まれる情報: 名前、住所、開店時間（今日/明日）
• 更新方法: npm run sync-stores を実行

拡張商品データ

• ソース: 個々の商品ページからスクレイピング
• 含まれる情報: 味のプロファイル、使用ヒント、提供方法の提案、食事との相性、証明書、成分
• キャッシュ: 最初のスクレイピング後にFirestoreに保存

📋 商品フィールド

💻 開発

npm run build        # TypeScriptをコンパイル
npm run dev          # tsxのウォッチモードで実行
npm run test         # ウォッチモードでテストを実行
npm run test:run     # テストを一度だけ実行（232件のテスト）
npm run typecheck    # 型チェック
npm run sync-data    # Excelから商品を同期
npm run sync-stores  # ウェブサイトから店舗をスクレイピング
npm run export-seed  # データをシードファイルにエクスポート（差分付き）

ログ

tail -f /tmp/alko-mcp.log

☁️ Google Cloud Runへのデプロイ

このサーバーは、ChatGPTや他のMCPクライアントとの互換性のため、公開アクセス（認証なし）でCloud Runにデプロイできます。

# APIを有効化
gcloud services enable run.googleapis.com firestore.googleapis.com artifactregistry.googleapis.com cloudbuild.googleapis.com

# Firestoreデータベースを作成
gcloud firestore databases create --location=europe-north1

# Cloud Buildを使用してデプロイ
gcloud builds submit --config=cloudbuild.yaml

# またはソースから直接デプロイ
gcloud run deploy alko-mcp \
  --source . \
  --region europe-north1 \
  --memory 2Gi \
  --cpu 2 \
  --execution-environment gen2 \
  --set-env-vars="MCP_TRANSPORT=http" \
  --allow-unauthenticated

エンドポイントをテスト

curl -X POST https://alko-mcp-xxx.a.run.app/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

APIトークン認証やその他のオプションについては、DEPLOYMENT.md を参照してください。

⚠️ 法律上の免責事項

• Alkoの価格表は公開データです。
• ウェブスクレイピングはレート制限（リクエスト間隔2秒）を守っています。
• これはAlko Oyとは関係のない非公式プロジェクトです。
• アルコール商品はフィンランドでは18歳以上の人のみが購入できます。

📄 ライセンス

MITライセンス