Seoul Cultural Events Reservation MCP Server

A Seoul Data MCP server for 문화행사 공공서비스예약 (Seoul Cultural Events Reservation)

TODO (REMOVE AFTER COMPLETING)

• [ ] Generate a uv.lock file with uv sync
• [ ] Remove the example tools in server.py
• [ ] Add your own tool(s) for Seoul Open Data API integration
• [ ] Implement API authentication and configuration
• [ ] Keep test coverage high
• [ ] Document the MCP Server in this README.md
• [ ] Test with MCP Inspector
• [ ] Test with Claude Code or other MCP clients

Overview

This MCP server provides tools to access Seoul Open Data API for 문화행사 공공서비스예약 (Seoul Cultural Events Reservation).

Features

• 🔍 Search cultural events by keyword and date range
• 📅 Filter events by genre and location
• 🚇 Access transportation information for cultural spaces
• 🏛️ Browse cultural space information

Installation

Using uvx (Recommended)

uvx data-seoul-mcp.culturalreservation-mcp-server@latest

Using uv pip

uv pip install data-seoul-mcp.culturalreservation-mcp-server

Configuration

Option 1: Using Published Package (uvx)

Add to your .mcp.json:

{
  "mcpServers": {
    "seoul-culturalreservation": {
      "command": "uvx",
      "args": ["data-seoul-mcp.culturalreservation-mcp-server@latest"],
      "env": {
        "SEOUL_API_KEY": "your-api-key-here",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

Option 2: Using Local Development Version

For local development and testing, add to your .mcp.json:

{
  "mcpServers": {
    "seoul-culturalreservation": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/culturalreservation-mcp-server",
        "run",
        "data_seoul_mcp/culturalreservation_mcp_server/server.py"
      ],
      "env": {
        "SEOUL_API_KEY": "your-api-key-here",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

Important: Replace /absolute/path/to/culturalreservation-mcp-server with the actual absolute path to your project directory.

Example:

{
  "mcpServers": {
    "seoul-culturalreservation": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/username/projects/culturalreservation-mcp-server",
        "run",
        "data_seoul_mcp/culturalreservation_mcp_server/server.py"
      ],
      "env": {
        "SEOUL_API_KEY": "12345678-abcd-efgh-ijkl-1234567890ab",
        "FASTMCP_LOG_LEVEL": "ERROR"
      }
    }
  }
}

Tools

ExampleTool

Example tool for testing the server setup.

Parameters:

• query (string): Test query string

SearchEvents

Search Seoul cultural events.

Parameters:

• keyword (string, optional): Search keyword for event title or description
• start_date (string, optional): Start date in YYYYMMDD format
• end_date (string, optional): End date in YYYYMMDD format
• limit (integer, default: 10): Maximum number of results

Development

Setup

# Clone the repository