Simpro MCP server

비공식. 이 프로젝트는 독립적인 서드파티 프로젝트입니다. Simpro와 관련이 없으며, Simpro의 보증이나 지원을 받지 않습니다.

AI 에이전트가 여러분의 Simpro 계정에서 작업할 수 있게 해 줍니다. Simpro에서 거의 모든 것을 조회하고, 보통 여러 화면을 클릭해야 얻을 수 있는 수치를 한곳에 모아 줍니다. 평범한 영어로 질문하면 에이전트가 Simpro에서 조회와 변경을 대신 수행합니다.

Simpro API 전체에 접근하므로, 전용 도구가 없는 작업도 에이전트가 여전히 처리할 수 있습니다.

⚠️ 이 도구는 읽기만 하는 것이 아니라 쓰기와 삭제도 할 수 있습니다. 레코드를 업데이트하고 삭제하는 엔드포인트를 포함한 Simpro API 전체에 접근합니다. 이를 구동하는 AI 에이전트는 실수나 잘못된 지시에 따라 운영 중인 Simpro 계정에서 견적, 작업, 고객, 카탈로그 항목 등을 대량으로 수정하거나 삭제할 수 있으며, 되돌릴 수 없습니다. 이 도구는 사용자가 부여한 키 또는 로그인의 권한으로 동작합니다. 신뢰할 수 없는 에이전트에게 넘겨주지 말고, 프로덕션 환경에서 무인으로 실행하지 말며, 실제로 필요한 범위로만 제한된 Simpro 로그인/키를 사용하세요. 읽기 전용 안전성을 원한다면 읽기 전용 권한을 가진 Simpro 사용자를 만들어 그 사용자로 인증하세요.

이 도구는 우리가 자체 MCP Gateway 뒤에서 사용하는 내부 도구에서 개발되었습니다. 커뮤니티를 위해 좀 더 기능적으로 만들기 위해 몇 가지 추가 기능을 더했지만, mcbp 및 OAuth Broker 모드는 내부적으로 사용하지 않습니다.

이 소프트웨어는 명시적이거나 묵시적인 어떠한 종류의 보증도 없이 "있는 그대로" 제공됩니다. 사용에 따른 위험은 사용자에게 있으며, 작성자는 이 도구 사용으로 인해 발생하는 Simpro 데이터의 손실, 손상 또는 변경에 대해 어떠한 책임도 지지 않습니다.

사전 요구 사항

• Claude Desktop 설치(옵션 1)의 경우: Claude Desktop과 Simpro OAuth 앱만 있으면 됩니다. .mcpb 번들에 자체 런타임이 포함되어 있습니다.

• 소스에서 실행하거나 자체 호스팅하는 경우(옵션 2 및 3): Node.js 24 이상과 npm이 필요합니다.

• 접근 가능한 Simpro 빌드와 해당 빌드에서 만든 OAuth 앱(또는 레거시 API 키)이 필요합니다. 각 모드의 섹션에 정확히 무엇이 필요한지 나와 있습니다.

Related MCP server: ServiceTitan MCP Server

목차

• Claude Desktop에 설치(간편한 방법)

  • Simpro에서 필요한 것

  • 설치

  • 로그인(OAuth 흐름)

  • 기타 인증 방법

  • 소스에서 로컬로 실행

• OAuth Broker 모드(AI 에이전트 커넥터용)

• HTTP 프록시 모드(공유/호스팅 설정용)

• 어떤 모드를 원하나요?

• 클라이언트 연결(구성 스니펫)

• 브로커가 Simpro 로그인을 업그레이드하는 방법

• 직접 빌드하기

1. Claude Desktop에 설치(간편한 방법)

명령줄도, 설정 파일도 필요 없습니다. Claude Desktop의 확장 프로그램 설정에서 .mcpb 번들을 설치하고 간단한 양식을 작성한 다음 브라우저에서 Simpro에 한 번 로그인하면 됩니다. 이후에는 에이전트가 로그인 상태를 유지하므로 그냥 대화만 하면 됩니다.

Simpro에서 필요한 것

Simpro OAuth 앱으로 인증합니다. 이 앱은 Simpro 자체 로그인 화면을 통해 로그인하게 해 주는 권장 방식입니다. Simpro에서 Setup → Integrations → API → New API Key 아래에서 OAuth/"Authorization Code" 애플리케이션을 만들어 다음을 적어 두세요.

한 가지 중요한 단계: Simpro OAuth 앱에서 Redirect URI를 http://localhost:8237/callback으로 설정하세요. 로그인 후 Simpro가 사용자를 이 주소로 돌려보냅니다. 이 주소는 정확히 일치해야 합니다. 머신에서 8237 포트를 이미 사용 중이라면 다른 포트를 선택하고 설치 화면에서 해당 Auth redirect port를 설정하세요. 단, 등록된 redirect URI도 같은 포트를 사용해야 합니다.

설치

1. 릴리스 페이지에서 최신 simpro-mcp-server.mcpb 파일을 다운로드합니다.

2. Claude Desktop에서 Settings → Extensions를 열고 Advanced settings를 클릭한 다음 Install extension을 클릭합니다(먼저 해당 화면에서 개발자/확장 프로그램 설치를 활성화해야 할 수 있습니다). 다운로드한 simpro-mcp-server.mcpb 파일을 선택하면 설치 화면이 나타납니다.

3. 다음을 입력합니다:

   • Build URL 및 Company ID

   • Authentication mode - authorization_code(브라우저 로그인)로 둡니다.

   • Simpro OAuth 앱의 Client ID 및 Client secret

   • 다른 포트를 등록하지 않았다면 Auth redirect port는 8237로 둡니다.

4. 설치를 클릭합니다.

로그인(OAuth 흐름)

에이전트가 도구를 처음 사용할 때 Simpro 로그인 화면이 브라우저 탭으로 열립니다. 로그인하고 액세스를 승인하세요. 탭에 **"✓ Authorised"**가 표시되면 탭을 닫고 채팅으로 돌아갑니다.

그 로그인 한 번이면 충분합니다. 도구가 리프레시 토큰을 캐시하므로 재시작 후에도 로그인 상태가 유지되며, 해당 토큰이 해지되거나 만료되기 전까지 다시 로그인을 요구하지 않습니다. 만약 그런 일이 발생하면 로그인 탭이 다시 열릴 뿐입니다.

이제 끝입니다. 채팅을 시작해서 "show me open quotes for Acme" 또는 "what's on job 4521?" 같은 것을 물어보세요.

Page size는 설치 화면의 선택 설정입니다. 50으로 두세요. 한 번에 반환되는 행 수를 제한하여 큰 목록이 한 답변을 압도하지 않도록 할 뿐이며, 에이전트는 언제든 더 요청할 수 있습니다.

기타 인증 방법

설치 화면의 Authentication mode 필드는 세 가지 선택지를 제공합니다.

자격 증명 안전하게 보관하기

클라이언트 시크릿, 리프레시 토큰 및 모든 API 키는 Claude Desktop에 저장되며 여러분 자신의 Simpro 빌드와 통신하는 데에만 사용됩니다. 이 값들을 가진 사람은 누구나 여러분이 부여한 것과 같은 액세스 권한으로 Simpro에서 작업할 수 있으므로, 그런 액세스 권한이 없어야 하는 사람과 .mcpb 설치 파일이나 해당 값을 공유하지 마세요. 자격 증명이 노출된 적이 있다면 Simpro에서 OAuth 앱이나 키를 해지하고 새로 만드세요.

소스에서 로컬로 실행

개발자, 또는 .mcpb 번들 대신 Git 체크아웃에서 실행하는 사람을 위한 내용입니다. 위에서 확장 프로그램을 설치했다면 건너뛰어도 됩니다.

1. .env.example을 .env로 복사하고 SIMPRO_BASE_URL과 SIMPRO_COMPANY_ID를 설정합니다. 또한 SIMPRO_CLIENT_ID + SIMPRO_CLIENT_SECRET(브라우저 로그인 또는 머신 로그인용) 또는 SIMPRO_API_KEY(레거시 키) 중 하나를 설정합니다.

2. 인증 모드는 설정한 값에 따라 결정됩니다. 클라이언트 ID와 시크릿이 모두 있으면 client_credentials, 그렇지 않으면 api_key입니다. 브라우저 로그인을 강제하려면 SIMPRO_AUTH_MODE=authorization_code로 설정하세요.

3. npm install && npm run build && npm start - 설치된 확장 프로그램과 동일하게 stdio로 실행됩니다.

브라우저 로그인(authorization_code)의 경우 npm run login으로 미리 한 번 로그인할 수 있습니다. Simpro 로그인 탭이 열리고 리프레시 토큰이 .simpro-tokens.json에 캐시됩니다. 이 단계를 건너뛰면 서버는 도구가 처음 사용될 때 동일한 로그인을 실행합니다. 전체 스크립트 목록은 직접 빌드하기를 참조하세요.

2. OAuth Broker 모드(AI 에이전트 커넥터용)

Simpro를 AI 에이전트에 적절한 커넥터로 연결하기 위한 모드입니다. 각 사용자가 공유 키나 개인별 설정 파일 없이 일반적인 Simpro 로그인 화면을 통해 직접 Simpro에 로그인합니다. 서버에서 실행하는 대부분의 사람들에게 이 모드가 바로 원하는 모드입니다.

제공되는 Docker 설정의 기본값도 이 모드입니다. 더 안전한 기본값입니다. 서버는 업스트림에서 전달받은 자격 증명을 신뢰하는 대신 사용자를 직접 인증합니다. 여전히 TLS를 종료하고 PUBLIC_URL을 서버로 라우팅하는 리버스 프록시 뒤에 있어야 하지만, 인바운드 헤더를 신뢰할지 결정하는 주체가 컨테이너가 되는 일은 없습니다.

Simpro 자체 로그인은 OAuth 2.0 설계라서 최신 에이전트 커넥터가 직접 연결하지 못합니다. 이 서버는 그 중간에서 그들이 요구하는 OAuth 2.1 표준에 맞게 끌어올립니다. Simpro에 없는 보안 단계를 추가하면서도 실제 Simpro 로그인으로는 계속 넘겨줍니다. 사용자 입장에서 보면 그저 "연결을 클릭하고 Simpro에 로그인"하는 것뿐입니다. 추가되는 정확한 단계는 아래 브로커가 Simpro 로그인을 업그레이드하는 방법에 설명되어 있습니다.

서버는 Simpro 앞에서 로그인 핸드셰이크를 실행합니다. 사용자는 자신의 에이전트에서 커넥터를 추가하고 Simpro에 로그인하도록 안내받은 후, 그때부터 에이전트는 그 사용자로서 Simpro에서 작업합니다. 사용자의 Simpro 액세스는 에이전트가 보유한 토큰 안에 봉인되며, 서버는 로그인 데이터베이스를 유지하지 않습니다.

이 모드에는 공개 웹 주소와 Simpro OAuth 앱(Simpro의 Setup → Integrations에서 생성)이 필요합니다. 해당 OAuth 앱에서 Redirect URL을 공개 주소 뒤에 /callback을 붙인 값으로 설정하세요. 예: https://simpro.yourcompany.com/callback.

설정

위의 SIMPRO_BASE_URL(및 선택적으로 SIMPRO_COMPANY_ID)에 더해 다음을 환경 변수로 설정하세요.

이 모드에서는 SIMPRO_API_KEY를 설정하지 마세요. 서버가 시작을 거부합니다.

3. HTTP 프록시 모드(공유/호스팅 환경용)

이미 로그인을 처리하는 무언가 뒤에 있는 서버에서 팀이 실행하는 경우를 위한 모드입니다(예: Cowork 또는 Copilot 설정). 이 모드에서 서버는 자체 Simpro 키를 보유하지 않습니다. 각 요청은 사용자를 로그인시키는 어떤 것이 첨부한 자체 로그인 정보를 가져옵니다. 서버는 이를 Simpro에 그대로 전달만 합니다.

⚠️ 인터넷 직접 노출용이 아님. 이 모드는 게이트웨이 또는 리버스 프록시(MCP 게이트웨이, Context Forge, 또는 nginx/Traefik 같은 것) 뒤에서 실행되어야 합니다. 해당 프록시가 TLS를 종료하고 사용자를 인증합니다. 이 모드는 자체 인증을 수행하지 않으며 직접 노출에 대비해 강화되지 않았습니다. 절대 인터넷에 직접 공개하지 마세요. 컨테이너는 의도적으로 호스트에 기본 게시되지 않습니다. 게이트웨이는 사설 네트워크에서 컨테이너에 접근합니다.

이 모드를 사용하려면 SIMPRO_TRANSPORT=proxy로 설정하세요(제공된 Docker 설정은 기본적으로 더 안전한 위의 브로커 모드를 사용합니다). Portainer 또는 Context Forge로 배포하는 경우 스택 구성은 docs/deploy.md를 참조하세요.

여기서는 API 키를 설정하지 않습니다. 실제로 키가 있으면 서버가 시작을 거부합니다. 이 모드에서는 사용자별 로그인이 액세스를 허용하는 유일한 수단이어야 하기 때문입니다.

중요 - 이 모드는 자체 검증을 수행하지 않습니다. 요청과 함께 도착하는 Authorization 헤더는 수정 없이 Simpro로 직접 전달됩니다. 서버는 자격 증명이 유효한지, 만료되지 않았는지, 또는 요청이 허용된 사용자로부터 왔는지 확인하지 않습니다. 자격 증명이 작동하는지 여부는 Simpro만이 결정합니다. 이는 의도된 설계입니다. 이 모드는 앞단의 계층(게이트웨이 또는 로그인 시스템)이 이미 사용자를 인증하고 신뢰할 수 있는 헤더를 첨부했다고 가정합니다. 이 모드는 반드시 그러한 계층 뒤에서만 실행하세요. 직접 노출하면 접근 가능한 사람은 누구나 자신의 헤더를 그대로 Simpro에 전달할 수 있습니다.

설정

이들은 환경 변수로 설정됩니다(.env 파일 또는 컨테이너 플랫폼에서).

이 모드에서는 SIMPRO_API_KEY를 설정하지 마세요. 서버가 시작을 거부합니다.

한 번에 반환되는 데이터 양도 조정할 수 있습니다:

4. 어떤 모드를 선택해야 하나요?

5. 클라이언트 연결(구성 스니펫)

Claude Desktop .mcpb 설치(옵션 1)는 자체 구성을 작성하므로 JSON을 건드릴 필요가 없습니다. 아래 스니펫은 소스 체크아웃에서 실행하거나 호스팅된 브로커/프록시에 클라이언트를 연결할 때 사용합니다.

Claude Desktop - 소스에서 stdio

claude_desktop_config.json을 편집합니다(설정 → 개발자 → 구성 편집). command를 node로, args를 빌드된 dist/index.js로 지정하고 Simpro 설정을 env로 전달합니다:

{
  "mcpServers": {
    "simpro": {
      "command": "node",
      "args": ["/absolute/path/to/simpro-mcp/dist/index.js"],
      "env": {
        "SIMPRO_BASE_URL": "https://yourbuild.simprosuite.com",
        "SIMPRO_COMPANY_ID": "0",
        "SIMPRO_AUTH_MODE": "authorization_code",
        "SIMPRO_CLIENT_ID": "your-oauth-client-id",
        "SIMPRO_CLIENT_SECRET": "your-oauth-client-secret"
      }
    }
  }
}

먼저 빌드하세요(npm install && npm run build). Windows에서는 이스케이프된 백슬래시가 포함된 전체 경로를 사용하세요("C:\\path\\to\\simpro-mcp\\dist\\index.js"). 레거시 키의 경우 클라이언트 ID/시크릿을 제거하고 대신 "SIMPRO_API_KEY"를 설정하세요(stdio 전용).

Claude Code - claude mcp add

CLI에서 동일한 stdio 서버를 등록합니다(체크아웃 디렉터리에서 실행하거나 절대 경로 사용):

claude mcp add simpro \
  --env SIMPRO_BASE_URL=https://yourbuild.simprosuite.com \
  --env SIMPRO_COMPANY_ID=0 \
  --env SIMPRO_AUTH_MODE=authorization_code \
  --env SIMPRO_CLIENT_ID=your-oauth-client-id \
  --env SIMPRO_CLIENT_SECRET=your-oauth-client-secret \
  -- node ./dist/index.js

호스팅된 브로커에 클라이언트 연결(옵션 2)

브로커가 공개 주소 뒤에서 실행되면 이를 원격 커넥터로 추가하세요. 로컬 명령이나 env는 없습니다. 클라이언트의 커넥터/"사용자 지정 커넥터 추가" UI를 사용하여 MCP URL을 지정하세요:

https://simpro.yourcompany.com/mcp

클라이언트는 로그인을 위해 Simpro로 리디렉션됩니다. 다른 구성은 필요 없습니다. (옵션 3의 HTTP 프록시도 같은 방식으로 접근하지만, 게이트웨이가 bearer를 첨부할 것을 기대합니다. 일반 커넥터로 추가되지 않습니다.)

6. 브로커가 Simpro의 로그인을 업그레이드하는 방식

이 섹션은 기술적으로 궁금한 분이나 커넥터의 보안을 검토하는 분을 위한 내용입니다. 위의 세 가지 모드를 사용하는 데는 필요하지 않습니다.

최신 에이전트 커넥터는 OAuth 2.1 기준을 충족하는 인증 서버에만 연결합니다. Simpro의 OAuth는 PKCE를 지원하지 않으며 해당 커넥터가 사용하는 클라이언트 ID 체계도 지원하지 않습니다. Simpro에 변경을 요청하는 대신, 브로커는 그 앞에서 자체적으로 OAuth 2.1을 준수하는 인증 서버 역할을 하며, 배후에서 조용히 Simpro로 중계합니다. 구체적으로 다음을 추가합니다:

• PKCE (S256) - 당사가 강제합니다. 연결하는 클라이언트는 /authorize에서 코드 챌린지를 보내고 /token에서 이를 증명해야 하며, 불일치하면 거부됩니다. Simpro 자체는 PKCE를 수행하지 않으므로 실제로 이를 강제하는 쪽은 브로커입니다. 일반 2.0이 남겨 두는 인가 코드 탈취 허점을 메웁니다.

• 현대적인 클라이언트 신원 - 클라이언트에 공유 시크릿이 내장되어 있지 않습니다. 연결하는 클라이언트는 두 가지 표준 방식 중 하나로 브로커에게 자신이 누구인지 알리며, 브로커는 주어진 클라이언트가 사용하는 방식을 수락합니다.

  • CIMD (client-ID-metadata-document): client_id는 브로커가 요청마다 가져와 검증하는 URL입니다. 자기 자신을 가리켜야 하며 사용 중인 정확한 리다이렉트 주소를 나열해야 합니다. 사전 등록된 것은 없습니다. 이 가져오기는 anti-SSRF 가드 뒤에서 실행되므로 해당 URL로 서버의 내부 네트워크를 조사할 수 없습니다.

  • DCR (동적 클라이언트 등록, RFC 7591): 클라이언트는 POST /register로 미리 자신만의 client_id를 발급받을 수 있습니다. 브로커는 메타데이터에서 이 엔드포인트를 알립니다. 등록은 인증 없이 공개되어 있으므로 비율/크기 제한이 적용되며, 한도에 도달하면 가장 오래된 항목을 축출합니다. 등록된 클라이언트는 영속화되어 재시작 후에도 유지됩니다. 클라이언트는 공개(시크릿 없음) 또는 기밀(브로커가 시크릿을 발급한 다음 토큰 단계에서 이를 요구)로 등록할 수 있습니다.

• 정확한 리다이렉트 일치. 클라이언트가 돌아갈 주소는 등록된 주소와 문자 하나까지 일치해야 합니다. 단지 "시작"만 일치해서는 안 됩니다.

• 수명이 짧고 대상(audience)이 한정된 토큰. 클라이언트가 받는 토큰은 브로커가 발급하는 것으로, 만료 시각이 찍혀 있고 이 특정 서버를 대상(audience)으로 묶여 있습니다. 실제 Simpro 토큰은 그 안에 암호화(sealed)되어 있습니다. 브로커는 토큰 데이터베이스를 유지하지 않습니다. 모든 토큰은 자체 완결적이며, 발급되는 리프레시 토큰은 최대 30일 수명으로 제한되어 유출된 토큰을 무한정 재생할 수 없습니다. 한 가지 예외: Simpro는 리프레시 토큰을 사용할 때마다 회전시키므로(각 갱신 시 이전 토큰이 소진됨), 브로커는 로그인별 현재 업스트림 리프레시 토큰을 메모리에만 몇 분간 보관합니다. 따라서 리프레시 응답을 놓친 클라이언트도 다시 로그인할 필요가 없습니다. 이 토큰은 디스크에 기록되지 않으며, 다음 번 성공적인 갱신(클라이언트가 현재 토큰을 보유하고 있음을 확인)이 이루어지면 폐기되고, 재시작하거나 몇 분간 유휴 상태가 되면 사라집니다.

결과적으로: 에이전트는 깔끔하고 현대적인 OAuth 2.1 공급자처럼 보이는 대상과 통신하며, 사용자는 여전히 실제 Simpro 화면에서 로그인하고, Simpro 흐름의 취약한 부분은 중간에서 보강됩니다. 전체 교환은 핸드셰이크가 진행되는 몇 초 동안만 메모리에서 연관되므로, 이 모드는 단일 인스턴스로 실행되어야 합니다. 로드 밸런서 뒤에 두지 마세요.

직접 빌드하기

코드를 사용하기만 하는 것이 아니라 작업 중이라면:

npm install
npm run build        # compile
npm test             # run the unit tests
npm run login        # one-time browser sign-in (authorization_code); caches the refresh token
npm run build:mcpb   # produce the simpro-mcp-server.mcpb install file
npm start            # run it locally

npm run login은 컴파일된 dist/login.js를 실행하므로 먼저 빌드해야 합니다. SIMPRO_CLIENT_ID와 SIMPRO_CLIENT_SECRET 설정이 필요합니다(위의 소스에서 로컬로 실행하기 참조).

순수하고 결정적인 부분들(검색 순위, 출력 형식, 라인 항목 경로, 인증 암호화/스토어 헬퍼)을 다루는 단위 테스트 스위트(npm test)가 있습니다. 린터는 없고 네트워크를 목킹하는 것도 없으므로, 변경 사항을 완전히 확인하려면 여전히 빌드하고 실제 Simpro 계정으로 시도해 봐야 합니다. 아키텍처 참고 사항과 알아 두면 좋은 Simpro API 특이점은 CLAUDE.md에 있습니다.