PLAB Football MCP
by anthony0727
README.md
# PLAB Football MCP
플랩풋볼의 **개인 참가 소셜매치**를 찾고, 내 일정을 확인하고, 선택한 경기에 신청하는 로컬 MCP 서버입니다. 공식 웹사이트를 브라우저로 열어 동작합니다. 플랩풋볼이 운영하는 공식 프로젝트는 아닙니다.
An unofficial local [Model Context Protocol](https://modelcontextprotocol.io/) server for finding, joining and checking your own [PLAB Football](https://www.plabfootball.com/) social matches in Korea. Runs over stdio; no API key or hosted service is required.
## 시작하기
[uv](https://docs.astral.sh/uv/getting-started/installation/), Git, 데스크톱 Google Chrome이 필요합니다. Python 3.12 이상을 사용합니다. Codex에서는 아래 명령으로 공개 릴리스를 등록한 뒤 새 채팅을 엽니다.
```sh
codex mcp add plab -- uvx --python 3.12 --from git+https://github.com/anthony0727/plab-football-mcp@v0.1.0 mcp-server-plab
```
다른 stdio MCP 클라이언트에서는 다음과 같이 등록합니다. 데스크톱 앱에서 `uvx`를 찾지 못하면 `command`에 해당 컴퓨터의 실행 파일 경로를 지정하세요.
```json
{
"mcpServers": {
"plab": {
"command": "uvx",
"args": ["--python", "3.12", "--from", "git+https://github.com/anthony0727/plab-football-mcp@v0.1.0", "mcp-server-plab"]
}
}
}
```
예를 들어 이렇게 요청할 수 있습니다.
- “내일 부산에서 저녁 7시 이후에 시작하는 소셜매치 찾아줘.” 날짜와 시작 시각은 한국 시간입니다.
- “내가 신청한 다음 경기 언제야? 실제 낸 금액도 확인해줘.” 목록에서 경기를 찾은 다음 개인 신청 상세를 확인합니다.
- “방금 고른 경기 1명, 12,000원 이하면 신청해줘.” 현재 경기·구장·일시와 실제 비용을 확인한 뒤 진행합니다.
## 도구
| 도구 | 하는 일 |
| --- | --- |
| `plab_list_matches` | 날짜·지역·시간·경기장으로 공개 매치 검색. 검색만으로 좌석을 잡지 않습니다. |
| `plab_match_details` | 경기 번호로 구장, 일정, 참가비, 성별·레벨 조건과 신청 가능 여부 확인. |
| `plab_list_my_matches` | 로그인한 계정의 다가오는 일정 조회. 경기 번호가 필요 없습니다. |
| `plab_check_application` | 지정한 경기의 개인 신청 내역과 표시된 실결제액 확인. |
| `plab_prepare_booking` | 선택한 경기를 전용 브라우저 창에 열고 로그인이나 다음 신청 단계를 안내. |
| `plab_booking_status` | 열린 신청 창에서 현재 단계와 금액을 다시 확인. |
| `plab_submit_application` | 승인한 경기 번호, 현재 화면의 일회용 토큰, 원화 한도로 신청 또는 결제 버튼을 한 번 누름. |
## 로그인과 신청
공개 조회는 로그인 없이 임시 Chrome 창을 열고, 확인이 끝나면 닫습니다. 개인 일정과 신청에는 별도 Chrome 프로필과 보이는 창을 사용합니다. 첫 이용 때 열린 공식 창에서 직접 로그인하면 다음에도 같은 프로필을 씁니다. 기존 브라우저의 쿠키를 가져오거나 비밀번호·인증번호를 대화에 입력할 필요가 없습니다.
`user_action`은 로그인·인증 등 사용자가 공식 창에서 해야 할 단계입니다. `ready`나 `review`는 제출 전 상태이고, 결제 금액·대상이 모호하면 `manual_review`에서 멈춥니다. 네트워크가 끊겨 `outcome_unverified`가 나오면 다시 신청하지 말고 `plab_check_application` 또는 [내 일정](https://www.plabfootball.com/calendar)에서 확인하세요. 개인 신청이 확인된 결과는 `confirmed`입니다. 캐시 충전이나 취소는 직접 공식 사이트에서 합니다.
로그인 프로필과 중복 제출을 막는 시도 기록은 운영체제의 사용자 앱 데이터 폴더 아래 `plab-booking`에 남습니다. 저장 위치는 `PLAB_DATA_DIR`로 바꿀 수 있습니다. 이 폴더에는 로그인 상태가 있으므로 계정별로 사용하고, 이슈나 저장소에 올리지 마세요. 두 클라이언트에서 같은 프로필을 동시에 열지 마세요.
## 개발과 검증
```sh
git clone https://github.com/anthony0727/plab-football-mcp.git
cd plab-football-mcp
uv sync --locked
uv run playwright install chromium
uv run pytest
uv build
```
테스트는 가상의 경기·신청 화면을 사용합니다. 실제 신청이나 결제는 발생하지 않습니다. Chrome 대신 Playwright Chromium을 쓰려면 위 명령으로 Chromium을 설치한 뒤 MCP 환경 변수 `PLAB_BROWSER_CHANNEL=chromium`을 설정하세요. 실제 사이트를 이용하려면 창을 띄울 수 있는 데스크톱 세션이 필요합니다.
[MIT License](LICENSE)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues