popup-seoul-mcp

MCP (Model Context Protocol) server for PopupHub Seoul - provides intelligent tools for searching and retrieving popup store information in Seoul.

Installation

npm install -g popup-seoul-mcp

Quick Start with Claude Desktop

1. Install the package globally:

   npm install -g popup-seoul-mcp

2. Add to your Claude Desktop configuration:

   Edit your Claude Desktop config file:

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

   Add the MCP server configuration:

   {
     "mcpServers": {
       "popup-seoul-mcp": {
         "command": "popup-seoul-mcp",
         "env": {
           "DATABASE_URL": "your-postgresql-connection-string"
         }
       }
     }
   }

3. Restart Claude Desktop to load the new MCP server.

Configuration

Required Environment Variables

| Variable | Description | Required | |----------|-------------|----------| | DATABASE_URL | PostgreSQL connection string | Yes |

Optional Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | LOG_LEVEL | Logging level (debug, info, warn, error) | info | | CACHE_SEARCH_TTL | Search cache TTL in seconds | 300 | | CACHE_DETAILS_TTL | Details cache TTL in seconds | 600 | | MAX_SEARCH_RESULTS | Maximum search results returned | 100 | | DEFAULT_SEARCH_LIMIT | Default search limit | 20 |

Example Configuration

{
  "mcpServers": {
    "popup-seoul-mcp": {
      "command": "popup-seoul-mcp",
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/popup_seoul_db",
        "LOG_LEVEL": "info",
        "CACHE_SEARCH_TTL": "300",
        "CACHE_DETAILS_TTL": "600"
      }
    }
  }
}

Available Tools

🔍 search_popups

Search for popup stores with comprehensive filtering options.

Parameters:

• location (string, optional): Area name (e.g., "성수", "강남", "홍대")
• date_range (object, optional):
  • start_date (string): ISO date format
  • end_date (string): ISO date format
• category (array, optional): Array of category strings
• status (string, optional): "active" | "upcoming" | "ended" | "all" (default: "all")
• keyword (string, optional): Search term for title/description
• sort_by (string, optional): "popularity" | "start_date" | "end_date" | "created_at" (default: "popularity")
• sort_order (string, optional): "asc" | "desc" (default: "desc")
• limit (number, optional): Maximum results, 1-100 (default: 20)
• offset (number, optional): Pagination offset (default: 0)

Example Usage in Claude:

"Search for active fashion popup stores in Seongsu area for the next month"

📋 get_popup_details

Get detailed information about a specific popup store.

Parameters:

• id (string, required): Unique popup identifier
• include_related (boolean, optional): Include related popup recommendations (default: false)
• include_stats (boolean, optional): Include view/favorite statistics (default: true)

Example Usage in Claude:

"Get detailed information about popup store ID 'popup_12345' with related recommendations"

Database Requirements

This MCP server requires a PostgreSQL database with the PopupHub Seoul schema. The required tables include:

• Popup - Main popup store information
• PopupImage - Gallery images for popups
• PopupStatistics - View counts, favorites, shares
• SearchQuery - Analytics for search queries

For database setup instructions, see the development repository.

Performance Features

• Smart Caching: Automatic caching with configurable TTLs
• Database Optimization: Efficient queries with proper indexing
• Input Validation: Comprehensive parameter validation
• Error Handling: Graceful error handling with meaningful messages

Troubleshooting

Common Issues

1. "Tool not found" error

   • Ensure Claude Desktop is restarted after configuration
   • Verify the MCP server is properly configured in claude_desktop_config.json

2. Database connection errors

   • Check DATABASE_URL environment variable
   • Ensure PostgreSQL database is running and accessible
   • Verify database schema is properly set up

3. Permission errors

   • Ensure the package is installed globally with proper permissions
   • Try running npm install -g popup-seoul-mcp with sudo if needed

Debugging

Enable debug logging by setting LOG_LEVEL=debug in your configuration:

{
  "mcpServers": {
    "popup-seoul-mcp": {
      "command": "popup-seoul-mcp",
      "env": {
        "DATABASE_URL": "your-connection-string",
        "LOG_LEVEL": "debug"
      }
    }
  }
}

Development

For development setup, database configuration, and contributing guidelines, see the development repository.

License

ISC

Support

• 📁 GitHub Repository
• 🐛 Report Issues
• 📖 MCP Documentation