mcpPaylocity MCP 서버

Paylocity API 엔드포인트에서 데이터를 가져오는 MCP(Model Context Protocol) 서버입니다.

구성 요소

자원

서버는 다음을 사용하여 Paylocity API 리소스를 구현합니다.

Paylocity 데이터에 액세스하기 위한 사용자 지정 paylocity:// URI 체계
다음과 같은 리소스를 이용할 수 있습니다.
- paylocity://employees/{company_id} - 회사의 모든 직원을 나열합니다.
- paylocity://employees/{company_id}/{employee_id} - 특정 직원에 대한 세부 정보를 가져옵니다.
- paylocity://earnings/{company_id}/{employee_id} - 특정 직원의 소득 데이터 가져오기
- paylocity://codes/{company_id}/{code_resource} - 특정 리소스에 대한 회사 코드를 가져옵니다.
- paylocity://localtaxes/{company_id}/{employee_id} - 특정 직원의 지역 세금을 가져옵니다.
- paylocity://paystatement/{company_id}/{employee_id}/{year}/{check_date} - 특정 날짜의 급여 명세서 세부 정보를 가져옵니다.

도구

서버는 다음 도구를 구현합니다.

fetch_employees - 회사의 모든 직원을 가져옵니다.
- 선택적인 company_id 매개변수를 사용합니다.
fetch_employee_details - 특정 직원의 세부 정보를 가져옵니다.
- 필수 employee_id 및 선택적 company_id 매개변수를 사용합니다.
fetch_employee_earnings - 특정 직원의 수입 데이터를 가져옵니다.
- 필수 employee_id 및 선택적 company_id 매개변수를 사용합니다.
fetch_company_codes - 특정 리소스에 대한 회사 코드를 가져옵니다.
- 필수 code_resource 및 선택적 company_id 매개변수를 사용합니다.
fetch_employee_local_taxes - 특정 직원의 지역 세금을 가져옵니다.
- 필수 employee_id 및 선택적 company_id 매개변수를 사용합니다.
fetch_employee_paystatement_details - 특정 날짜의 급여 명세서 세부 정보를 가져옵니다.
- 필수 employee_id , year , check_date 및 선택적 company_id 매개변수를 사용합니다.

향후 구현

다음 엔드포인트는 향후 업데이트에서 구현될 예정입니다.

[ ] 상위 수준의 통찰력(예: 이직률, 부서별 직원 수, 요율 비교 등)

구성

서버에는 다음 환경 변수를 설정해야 합니다.

PAYLOCITY_CLIENT_ID - Paylocity API 클라이언트 ID
PAYLOCITY_CLIENT_SECRET - Paylocity API 클라이언트 비밀번호
PAYLOCITY_COMPANY_IDS - 사용할 회사 ID의 쉼표로 구분된 목록
PAYLOCITY_ENVIRONMENT - 사용할 API 환경( production 또는 testing )

이는 프로젝트 루트 디렉토리의 .env 파일에서 설정할 수 있습니다.

보안

⚠️ 중요 : 이 애플리케이션은 src/mcppaylocity/access_token/ 디렉터리에 인증 토큰을 캐시합니다. 이 파일에는 민감한 자격 증명이 포함되어 있으므로 버전 관리에 커밋해서는 안 됩니다.

저장소에는 이러한 경로가 .gitignore 에 포함되어 있지만 변경 사항을 푸시할 때 토큰 파일이 실수로 커밋되지 않도록 확인하세요.

실수로 토큰 파일을 커밋한 경우 다음 단계를 따르세요.

저장소에서 파일을 제거합니다: git rm --cached src/mcppaylocity/access_token/token.json src/mcppaylocity/access_token/token_info.txt
제거를 커밋합니다: git commit -m "Remove accidentally committed token files"
Paylocity API 자격 증명이 손상되었을 수 있으므로 해당 자격 증명을 교체하는 것을 고려하세요.

빠른 시작

설치하다

클로드 데스크탑

MacOS의 경우: ~/Library/Application\ Support/Claude/claude_desktop_config.json Windows의 경우: %APPDATA%/Claude/claude_desktop_config.json

지엑스피1

"mcpServers": {
  "mcpPaylocity": {
    "command": "uvx",
    "args": [
      "mcppaylocity"
    ]
  }
}

개발

건축 및 출판

배포를 위해 패키지를 준비하려면:

종속성 동기화 및 잠금 파일 업데이트:

uv sync

패키지 배포 빌드:

uv build

이렇게 하면 dist/ 디렉토리에 소스와 휠 배포판이 생성됩니다.

PyPI에 게시:

uv publish

참고: 환경 변수나 명령 플래그를 통해 PyPI 자격 증명을 설정해야 합니다.

토큰: --token 또는 UV_PUBLISH_TOKEN
또는 사용자 이름/비밀번호: --username / UV_PUBLISH_USERNAME 및 --password / UV_PUBLISH_PASSWORD

디버깅

MCP 서버는 stdio를 통해 실행되므로 디버깅이 어려울 수 있습니다. 최상의 디버깅 환경을 위해서는 MCP Inspector 사용을 강력히 권장합니다.

다음 명령을 사용하여 npm 통해 MCP Inspector를 시작할 수 있습니다.

npx @modelcontextprotocol/inspector uv --directory /path/to/mcpPaylocity run mcppaylocity

Inspector를 실행하면 브라우저에서 접근하여 디버깅을 시작할 수 있는 URL이 표시됩니다.

건축학

서버는 다음 구성 요소로 구축되었습니다.

PaylocityClient - Paylocity API와의 통신을 처리합니다.
TokenManager - 캐싱 및 갱신을 포함한 인증 토큰을 관리합니다.
FastMCP 서버 - MCP 리소스 및 도구를 통해 Paylocity 데이터를 노출합니다.

특허

MIT 라이센스

본 소프트웨어 및 관련 문서 파일(이하 "소프트웨어")의 사본을 취득한 모든 사람에게 소프트웨어를 제한 없이 거래할 수 있는 권한을 무상으로 부여합니다. 여기에는 소프트웨어 사본을 사용, 복사, 수정, 병합, 게시, 배포, 하위 라이선스 및/또는 판매할 수 있는 권한이 포함되나 이에 국한되지 않으며, 소프트웨어가 제공된 사람에게도 이러한 권한을 부여합니다. 단, 다음 조건에 따라야 합니다.

본 소프트웨어는 상품성, 특정 목적 적합성 및 비침해에 대한 보증을 포함하되 이에 국한되지 않는 명시적 또는 묵시적 보증 없이 "있는 그대로" 제공됩니다. 어떠한 경우에도 저작자 또는 저작권자는 본 소프트웨어 또는 본 소프트웨어의 사용 또는 기타 거래와 관련하여 발생하는 계약, 불법 행위 또는 기타 소송을 포함한 모든 청구, 손해 또는 기타 책임에 대해 책임을 지지 않습니다.

Integrations