Content
# GIS Accessibility MCP
This is an MCP (Model Context Protocol) server that allows for conversational analysis of **medical facility accessibility** at the eup-myeon-dong level in Korea, similar to interacting with Claude.
> This server works with Claude Desktop and Claude Code (CLI).
## Supported Analysis Indicators
| Method | Description | Paper Classification |
|------|------|-----------|
| `MIN` | Minimum distance to the nearest facility | Proximity-based |
| `K_AVG` | Average distance to the k nearest facilities | Proximity-based |
| `COM` | Cumulative opportunity indicator (number of facilities within threshold) | Opportunity-based (threshold) |
| `GRAVITY` | Accessibility based on gravity model | Opportunity-based (distance-decay) |
| `PPR` | Administrative unit supply ÷ population (non-spatial baseline, no threshold needed) | Opportunity-based (non-spatial baseline) |
| `2SFCA` | Two-step floating catchment area method | Competition-adjusted |
| `E2SFCA` | Enhanced 2SFCA (with distance decay) | Competition-adjusted |
> For indicator selection criteria, refer to [Ahn et al. (2026)](#related-papers) and `GIS-ACCESSIBILITY-SKILL.zip` > `references/methodology.md`.
## Quick Start
### 0. Prerequisites
The following software must be installed:
| Software | Description | Download |
|---|---|---|
| **Python 3.9 or higher** | Analysis engine | [python.org](https://www.python.org/downloads/) |
| **Node.js 18 or higher** | File access MCP (`gis-filesystem`) | [nodejs.org](https://nodejs.org/) |
| **Git** | Repository cloning | [git-scm.com](https://git-scm.com/downloads) |
| **Claude Desktop** | Claude GUI client *(either one)* | [claude.ai/download](https://claude.ai/download) |
| **Claude Code CLI** | Terminal Claude client *(either one)* | `npm install -g @anthropic-ai/claude-code` |
> Only one of Claude Desktop or Claude Code CLI is required.
> Node.js is not required for core analysis functionality, but is needed for Claude to directly read result files.
**Verify Git installation:**
```bash
git --version
# Example output: git version 2.x.x
```
If Git is not installed, download and install it from [git-scm.com/downloads](https://git-scm.com/downloads), then reopen the terminal or PowerShell and verify again.
### 1. Clone Repository
**Mac / Linux — Terminal:**
```bash
git clone https://github.com/Huijae-Kim/gis-accessibility-mcp.git
cd gis-accessibility-mcp
```
**Windows — PowerShell:**
> ⚠️ Windows users must run `install.ps1` in PowerShell. Use PowerShell from the beginning.
```powershell
git clone https://github.com/Huijae-Kim/gis-accessibility-mcp.git
cd gis-accessibility-mcp
```
> If Git is installed, you can use the `git` command directly in PowerShell.
> After installation, reopen PowerShell to recognize the command.
### 2. One-Click Installation
> ⚠️ **Completely close Claude Desktop before installation.**
> If Claude Desktop is running, it will overwrite the configuration file with its own state, invalidating MCP registration.
> - **Mac:** Menu bar Claude icon > Quit / `Cmd+Q`
> - **Windows:** System tray icon > Exit
**Mac / Linux:**
```bash
bash install.sh
```
**Windows (PowerShell):**
```powershell
# Run once (allow script execution)
Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
.\install.ps1
```
This script will automatically:
1. Create a Python virtual environment (`/.venv`) and install packages
2. Download data
3. Register MCP server with Claude Desktop configuration file (`gis-accessibility` + `gis-filesystem`)
4. Register MCP server with Claude Code CLI
5. Prepare Skill file (`GIS-ACCESSIBILITY-SKILL.zip`, `~/.claude/commands/gis-accessibility.md`)
### 3. Run Claude Desktop and Activate Skill
After installation, run Claude Desktop.
**+** → Check if `gis-accessibility` and `gis-filesystem` are listed in the connectors (takes about 1-2 minutes).
**Activate Skill (environment-specific):**
| Environment | Method |
|------|------|
| **Claude Desktop** | Top menu > Custom > Skills > **+** > Upload Skill > Select `GIS-ACCESSIBILITY-SKILL.zip` |
| **Claude Code CLI** | Run `claude` in terminal > Enter `/gis-accessibility` (automatically installed) |
## Manual Installation (Optional)
If automatic installation (`install.sh` / `install.ps1`) fails or you want to set it up manually:
### Package Installation
```bash
pip install -r requirements.txt
```
### Data Download
Download necessary data files (about 260MB) to the `_data/` folder.
**Method A: Automatic download (recommended)**
```bash
python download_data.py
```
**Method B: Manual download**
Download `data.zip` from [here](https://drive.google.com/file/d/1yQ97HCBKR1W_G_R2-a2iP_O4jcWTNsrz/view?usp=sharing), unzip it, and create the `_data/` folder. Move the `_data/` folder to the `gis-accessibility` folder.
> **Required files:**
> - `POPULATION_DONG_FINAL.csv`
> - `HOSPITALS_FINAL.csv`
> - `BND_ADM_DONG_PG.shp` (and related files)
> - `BND_SIGUNGU_PG.shp` (and related files)
### Manual MCP Registration with Claude Desktop
Configuration file location:
- **Mac:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
Add the following content:
```json
{
"mcpServers": {
"gis-accessibility": {
"command": "/absolute/path/gis-accessibility/.venv/bin/python3",
"args": ["/absolute/path/gis-accessibility/gis_analysis_v7.py"]
},
"gis-filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/absolute/path/gis-accessibility"]
}
}
}
```
> Windows path example: `"command": "C:\\Users\\username\\gis-accessibility\\.venv\\Scripts\\python.exe"`
>
> `gis-filesystem` allows Claude to directly read analysis result files in the `_results/` folder. Node.js is not required if you skip this.
### Manual MCP Registration with Claude Code CLI
```bash
claude mcp add gis-accessibility /absolute/path/.venv/bin/python3 /absolute/path/gis_analysis_v7.py
```
### Manual Skill Installation
**Mac / Linux:**
```bash
mkdir -p ~/.claude/commands
unzip -p GIS-ACCESSIBILITY-SKILL.zip "GIS-ACCESSIBILITY-SKILL/SKILL.md" > ~/.claude/commands/gis-accessibility.md
```
**Windows (PowerShell):**
```powershell
$dest = "$env:USERPROFILE\.claude\commands"
New-Item -ItemType Directory -Force -Path $dest | Out-Null
$tmp = "$env:TEMP\gis-skill-tmp"
Expand-Archive -Path GIS-ACCESSIBILITY-SKILL.zip -DestinationPath $tmp -Force
Copy-Item "$tmp\GIS-ACCESSIBILITY-SKILL\SKILL.md" "$dest\gis-accessibility.md" -Force
Remove-Item $tmp -Recurse -Force
```
## Example Usage
Interact with Claude Desktop or Claude Code in natural language:
```
Analyze pediatric accessibility in Seoul using the 2SFCA method
```
```
What are the areas with mental health medical shortages in Chungcheong Province?
```
```
Quickly check internal medicine accessibility in Daejeon using the PPR indicator
```
Result files (map images, CSV) are saved in the `_results/` folder.
## File Structure
```
gis-accessibility/
├── gis_analysis_v7.py # MCP server main code
├── requirements.txt # Python package list
├── download_data.py # Data download script
├── install.sh # One-click installation script (Mac/Linux)
├── install.ps1 # One-click installation script (Windows PowerShell)
├── GIS-ACCESSIBILITY-SKILL.zip # Claude Skill file (Desktop + Code)
│ ├── SKILL.md # Claude Code CLI slash command
│ ├── gis-accessibility.skill # Claude Desktop skill file
│ └── references/
│ └── methodology.md # Methodology reference
├── _data/ # Data folder (Git excluded, separate download)
│ ├── POPULATION_DONG_FINAL.csv
│ ├── HOSPITALS_FINAL.csv
│ ├── BND_ADM_DONG_PG.shp
│ └── BND_SIGUNGU_PG.shp
└── _results/ # Analysis result storage (automatically generated)
├── result_2SFCA_서울특별시_산부인과.png
└── result_2SFCA_서울특별시_산부인과.csv
```
## Data Sources
- Administrative boundary: Statistical Geographic Information Service (SGIS)
- National hospital and clinic status: Health Insurance Review and Assessment Service (HIRA) public data
- Population data: Ministry of Interior and Safety resident registration population statistics
## Related Papers
Ahn, J., Kim, H., & Lee, T. (2026). *A Conceptual Framework for Spatial Accessibility: Aligning Metrics with Urban Service Determinants*. KAIST ISysE Preprint.
## License
This project is licensed under the [CC BY-NC 4.0 License](https://creativecommons.org/licenses/by-nc/4.0/).
You are free to use and modify this work for **non-commercial purposes** with proper attribution.
Commercial use is **prohibited** without prior written permission.
## Acknowledgements
This research was supported by the **Center for Advanced Urban Systems (CAUS)** of Korea Advanced Institute of Science and Technology (KAIST), funded by **GS E&C**.
</div>
