tlc-portal-mcp

This is a stdio-based MCP server that allows MCP clients like Claude Code and Codex to use the vacation and timetable functions of the TwolineCloud portal.

By running the package with npx, you can use MCP tools for tasks such as browser login, leave inquiry/application, timetable inquiry/entry, and version diagnostics.

Currently Supported Features

• Portal login and authentication status check

• Inquiry of leave types, remaining leave, and leave application history

• Leave application and cancellation

• Timetable management information, available entry periods, and daily details

• Inquiry of timetable project lists

• Calculation of daily available hours reflecting leave

• Preparation and submission of single/period timetable entries

• Full daily deletion of timetable entries

• Checking the current server version and comparing it with the latest npm version

Related MCP server: ATimeLogger MCP Server

Requirements

• Node.js 18+

• A browser environment capable of portal login

Installation and Registration

Claude Code

# 사용자 전역 등록
claude mcp add tlc-portal-mcp --scope user -- npx -y tlc-portal-mcp

# 현재 프로젝트에만 등록
claude mcp add tlc-portal-mcp -- npx -y tlc-portal-mcp

Codex CLI

# 사용자 전역 등록
codex mcp add tlc-portal-mcp -- npx -y tlc-portal-mcp

Since Codex does not currently have a separate add command for project-specific use, you can add it directly to .codex/config.toml in the project root if needed.

[mcp_servers.tlc-portal-mcp]
command = "npx"
args = ["-y", "tlc-portal-mcp"]

Execution Method Notes

• mcp add ... -- npx -y tlc-portal-mcp is not a global installation but an execution command registration.

• The actual package download occurs when the client runs the server for the first time.

• It is not re-installed every time; cached versions may be reused depending on the execution environment.

• Therefore, the server includes system.* tools to check the current version against the latest version.

Authentication Methods

Recommended: auth.login

When the user logs in manually via the opened browser, the JWT from localStorage['vuex'] is automatically saved.

1. Run auth.login

2. Complete portal login and MFA in the browser

3. Token is automatically saved after successful login

4. Check authentication status with auth.status

An instruction overlay is displayed in the browser after a successful login.

Alternative: auth.import_vuex

If the automatic login flow is difficult to use, you can manually copy and paste the vuex value from the browser.

1. Log in to the portal in the browser

2. Go to Application > Local Storage > https://portal.twolinecloud.com in DevTools

3. Copy the vuex value

4. Run auth.import_vuex and paste the value

Tool List

System

Authentication

Leave

Timetable

Timetable Rules

• The default available entry time is 8 hours per day.

• If there is a half-day leave (AM, PM, admitAm, admitPm), you can record a maximum of 4 hours.

• If there is a full-day leave (allDay, admit), you cannot record entries for that date.

• South Korean public holidays are primarily retrieved from the Nager.Date API, with built-in fallback data used upon failure.

• Weekends and company-wide holidays (PORTAL_COMPANY_HOLIDAYS) are also treated as non-entry days.

• Personal leave overlays are calculated based on the requestDt sorting results from vacation-svc/request/secure in accordance with portal overview rules.

• workDate and taskType are always required.

• projectId is required by default.

• However, if taskType === NORMAL, you can enter without a projectId.

• Write operations follow the prepare -> submit flow.

Recommended Usage Order

Initial Diagnosis

1. system.info

2. system.check_update

3. auth.status

4. auth.login if necessary

Leave Flow

1. leave.get_balances

2. leave.list_requests

3. leave.prepare_request

4. leave.submit_prepared_request

Timetable Flow

1. timetable.get_available_range

2. timetable.get_range_overview

3. timetable.list_projects

4. timetable.get_day_capacity

5. timetable.prepare_day_entry or timetable.prepare_bulk_entries

6. timetable.submit_prepared_day_entry or timetable.submit_prepared_bulk_entries

Usage Examples

"현재 서버 버전이랑 최신 버전 비교해줘"
-> system.check_update

"내 휴가 잔여 일수 보여줘"
-> leave.get_balances

"이번 달 휴가 신청 이력 보여줘"
-> leave.list_requests

"4월 30일 오전 반차 신청 준비해줘"
-> leave.prepare_request

"오늘 입력 가능한 타임테이블 시간 계산해줘"
-> timetable.get_day_capacity

"2026년 2월 타임테이블 전체를 공휴일 포함해서 요약해줘"
-> timetable.get_range_overview

"2026-04-05에 프로젝트 274로 4시간, taskType EXECUTE로 입력 준비해줘"
-> timetable.prepare_day_entry

"오늘 일반업무 2시간, taskType NORMAL로 입력 준비해줘"
-> timetable.prepare_day_entry

"4월 1일부터 4월 3일까지 같은 내용으로 일괄 입력 준비해줘"
-> timetable.prepare_bulk_entries

Environment Variables

Limitations

• The JWT validity period is currently about 2 hours.

• If the token expires, you must run auth.login or auth.import_vuex again.

• Refresh tokens are not used.

• The session file is stored only locally and is not uploaded to the server.

• system.check_update can only check the latest version in environments with access to the npm registry.

• If the public holiday lookup API fails, it defaults to built-in fallback data.

• The NORMAL + no projectId combination for the timetable is implemented as an allowed flow based on documentation, but actual acceptance by the portal backend needs to be verified in the production environment.