seoul-uncomfort-report-mcp

This is an MCP server that queries Seoul Smart Complaint Report Statistics by Sector, Seoul Complaint Report Counts by Location, and Seoul Complaint Report Counts by Year/Month. It is based on the Seoul Open Data Plaza (data.seoul.go.kr) open API.

Dataset Registry Integrated into This MCP

This table is the "component list" of this MCP. Before adding a new dataset or creating a new MCP, check this table first — the left column is exactly what appears on the Seoul Open Data Plaza (data.seoul.go.kr) list screen, so you can compare it directly with what you see on screen. There is no need to reopen the API code name (SERVICE) or other documents; this single table is enough to make the decision.

Since the list order on screen (sorted by modification date) may change, the judgment criteria should always be whether the "dataset name" and "providing department" columns match. The order can be ignored.

How to Judge Within 3 Seconds When You See a New Dataset

1. If the dataset name on screen is already in the left column of the table above → No action needed (duplicate).

2. If the dataset name is new, but the providing department is "Digital City Bureau, Spatial Information Division" and the description contains "Seoul Smart Complaint Report" → Consider adding a tool to this MCP.

3. If the providing department is different (e.g., a dataset provided by another department such as "Sidewalk Facilities Management" or "Labor Union") → Not related to this MCP. Proceed with a completely new MCP project.

This table was created with the exact screen-capture names so that you can compare it directly by eye, without needing to call the API or ask Claude.

Related MCP server: sbinfo

Provided Tools

1. get_uncomfort_report_by_sector

Queries the number of complaint reports by sector (traffic, roads, cleaning, housing/construction, flood control, roadside maintenance, health, park/green space, environment, economy/industry, fire safety, and other inconveniences). Unit: number of reports.

Parameters: year (optional), month (optional), start_index (default 1), end_index (default 20)

2. get_uncomfort_report_by_district

Queries the number of complaint reports by Seoul's 25 districts plus other regions. Unit: number of reports.

Parameters: year (optional), month (optional), start_index (default 1), end_index (default 20)

3. get_uncomfort_report_by_month

Queries the number of complaint reports for each month (January to December) along with the annual total. Unit: number of reports. Note: This service does not have a MONTH parameter — only yearly data can be queried. Months that have not yet passed will have no data (e.g., if the query date is July 2026, August through December will have no values).

Parameters: year (optional), start_index (default 1), end_index (default 20)

Installation and Running (Local)

pip install -r requirements.txt
cp .env.example .env  # SEOUL_API_KEY 입력
python server.py

Environment Variables

Deployment

For fly.io deployment, follow the common project guidelines in CLAUDE.md. After deployment, when connecting via the Claude connector, append /mcp to the URL. Example: https://seoul-uncomfort-report-mcp.fly.dev/mcp

Data Source and License

• Providing Institution: Seoul Metropolitan Government

• Providing Department: Digital City Bureau, Spatial Information Division

• Source System: Seoul Smart Complaint Report

• License Scope: Korea Open Government License Type 1 (attribution required, commercial use and modification permitted)

Known Limitations (Verified by Actual Testing)

• The authentication key works when passed as a URL path segment (e.g., /{KEY}/json/{SERVICE}/...). The query parameter method was not tested (the path method succeeded on the first attempt).

• All 3 services (SmartUncomfStatSector, SmartUncomfStatLocale, SmartUncomfStatMonth) work normally with a single SEOUL_API_KEY (verified by actual testing).

• All combinations of YEAR/MONTH selection parameters — omitting all, specifying only YEAR, and specifying both YEAR and MONTH — work normally. SmartUncomfStatMonth has no MONTH parameter at all, so it works with YEAR only (verified by actual testing).

• In the API response, the JSON structure may differ depending on whether the result is a single record or multiple records (single dict vs. list), so the server internally normalizes the response to always be a list.

• Numeric fields come as floats in JSON (e.g., 55567.0). Empty tags for months that have not yet passed (e.g., MON_08) come as 0.0 rather than null. The server safely converts all of them to integers before returning.

• This server is publicly accessible without API key authentication, and rate limiting is applied based on IP address (3 requests per minute, 5 violations within 1 hour results in a 24-hour block, 30 requests total per 24 hours — when deployed across multiple machines, the effective limit may be relaxed in proportion to the number of machines).

License

MIT