dandacompany/webhook-trigger

@dandacompany

FastMCP 프레임워크를 사용한 동적 웹훅 전송 MCP 서버입니다.

webhook

fastmcp

claude-integration

python

http-requests

FastMCP 웹훅 서버

FastMCP 프레임워크를 사용한 동적 웹훅 전송 MCP 서버입니다.

기능

GET 방식 웹훅 전송
POST 방식 웹훅 전송
커스텀 HTTP 메서드 지원 (PUT, DELETE, PATCH 등)
사용자 정의 헤더 및 페이로드 지원
헤더 인증 지원

설치 및 실행

가상환경 설정 및 종속성 설치:

# 가상환경 활성화
source venv/bin/activate

# 종속성 설치
pip install -r requirements.txt

서버 실행:

# 방법 1: 개발 모드 (웹 인터페이스 제공)
fastmcp dev main.py

# 방법 2: 직접 실행
python main.py

# 방법 3: Claude Desktop에 설치
fastmcp install main.py --name "Webhook Server"

Claude Desktop에 MCP 서버 설정하기

전제 조건

Claude Desktop 설치 (https://claude.ai/desktop)
FastMCP 설치 (pip install fastmcp)
uv 설치 (macOS에서는 brew install uv)

설치 과정

터미널에서 다음 명령어를 실행하여 MCP 서버를 Claude Desktop에 설치합니다:

cd dante@webhook_trigger
fastmcp install main.py --name "Webhook Server"

환경 변수가 필요한 경우 다음과 같이 설정할 수 있습니다:

# .env 파일에서 불러오기
fastmcp install main.py --name "Webhook Server" -f .env

설치 성공 메시지가 표시되면, Claude Desktop을 실행합니다.
Claude Desktop 앱에서:
- 좌측 하단의 설정 아이콘(⚙️)을 클릭합니다.
- "Extension & Tools" 메뉴로 이동합니다.
- "Installed Tools" 섹션에서 "Webhook Server"가 표시되는지 확인합니다.
- 필요한 경우 토글 스위치로 활성화합니다.

claude_desktop_config.json 수동 설정 방법

FastMCP의 설치 명령어는 자동으로 Claude Desktop의 설정 파일을 업데이트합니다. 하지만 수동으로 설정하거나 문제가 발생한 경우 다음 방법을 사용할 수 있습니다:

claude_desktop_config.json 파일 위치:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: C:\\Users\\YourUsername\\AppData\\Roaming\\Claude\\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
웹훅 MCP 서버를 위한 설정 추가 (가상환경 사용):

{
  "mcpServers": {
    "webhook-server": {
      "command": "/absolute/path/to/dante@webhook_trigger/venv/bin/python",
      "args": [
        "/absolute/path/to/dante@webhook_trigger/main.py"
      ],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

쉘 스크립트를 통한 실행 방식 (권장):

{
  "mcpServers": {
    "webhook-server": {
      "command": "/bin/bash",
      "args": [
        "/absolute/path/to/dante@webhook_trigger/mcp_run.sh"
      ],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

uv를 사용한 실행 방식:

{
  "mcpServers": {
    "Webhook Server": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "/absolute/path/to/dante@webhook_trigger/main.py"
      ],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

uv와 가상환경을 사용한 실행 방식 (권장):

{
  "mcpServers": {
    "Webhook Server": {
      "command": "/bin/bash",
      "args": [
        "-c",
        "cd /absolute/path/to/dante@webhook_trigger && uv run python main.py"
      ],
      "env": {
        "DEBUG": "true"
      }
    }
  }
}

설정 파일 구성 요소:
- mcpServers: MCP 서버 목록이 포함된 객체
- webhook-server: 서버의 식별자(이름)로, Claude에 표시됩니다
- command: 서버를 실행할 명령어 (가상환경의 Python 경로 사용)
- args: 명령어에 전달할 인수 배열
- env: 환경 변수 설정 (선택 사항)
macOS에서 경로 설정 주의사항:
- 절대 경로 사용을 권장합니다
- 가상환경의 Python 경로를 정확히 지정해야 합니다
- 홈 디렉토리(~)는 명시적으로 전체 경로로 변경해야 합니다
- 경로에 공백이 있는 경우 적절하게 처리해야 합니다
설정 적용:
- 설정 파일을 저장한 후 Claude Desktop을 재시작합니다
- Tools 섹션에서 웹훅 서버가 표시되는지 확인합니다

설치 확인 및 테스트

Claude Desktop에서 새 대화를 시작합니다.
다음과 같은 프롬프트를 입력하여 MCP 서버가 제대로 작동하는지 테스트합니다:

"Webhook Server"를 사용하여 https://httpbin.org/get에 GET 요청을 보내줄래?

Claude가 MCP 서버의 도구를 사용하여 요청을 처리하고 결과를 반환하는지 확인합니다.

문제 해결

서버가 보이지 않는 경우:
```
fastmcp list
```
명령어로 설치된 서버 목록을 확인하고, 필요한 경우 재설치합니다.
Claude가 도구를 인식하지 못하는 경우: Claude Desktop을 재시작하고, 설정에서 도구가 활성화되어 있는지 확인합니다.
macOS에서 uv 관련 오류:
```
brew install uv
```
를 실행하여 uv가 시스템 경로에 올바르게 설치되었는지 확인합니다.
config.json 설정 문제:
- 경로가 올바른지 확인합니다
- JSON 형식에 오류가 없는지 확인합니다
- 명령어와 실행 파일의 권한이 적절한지 확인합니다
Python 가상환경 문제:
- 가상환경의 Python 경로가 올바른지 확인합니다
- 필요한 패키지가 가상환경에 설치되어 있는지 확인합니다
- 쉘 스크립트를 통한 실행 방식을 사용해보세요

MCP 서버 사용 방법

1. MCP 개발 인터페이스 (Inspector) 사용

개발 모드에서는 웹 인터페이스를 통해 다음 작업을 수행할 수 있습니다:

도구 목록 확인
도구 테스트
로그 확인

2. Claude에서 사용

Claude Desktop에 설치한 후 다음과 같이 자연어로 요청할 수 있습니다:

GET 요청 예시

https://example.com/api에 GET 요청을 보내줘.

다음 정보로 GET 웹훅을 보내줘:
- URL: https://api.example.com/users
- 헤더: {"Accept": "application/json"}
- 인증 토큰: "Bearer token123"

POST 요청 예시

https://example.com/api에 {"name": "테스트"}라는 데이터를 POST로 보내줘.

다음 정보로 POST 웹훅을 보내줘:
- URL: https://api.example.com/webhook
- 헤더: {"Content-Type": "application/json", "X-API-Key": "key123"}
- 페이로드: {"name": "테스트", "value": 123}
- 인증 토큰: "Bearer token456"

커스텀 HTTP 메서드 예시

https://example.com/api/user/1에 DELETE 요청을 보내줘.

다음 정보로 PUT 요청을 보내줘:
- URL: https://api.example.com/users/123
- 페이로드: {"name": "수정된 이름", "email": "[email protected]"}
- 인증: "Bearer my-token"

사용 가능한 MCP 도구

1. `send_get_webhook`

GET 방식으로 웹훅을 전송합니다.

매개변수:

url: 호출할 웹훅 URL (필수)
auth_token: 인증에 사용할 토큰 (선택 사항)
custom_headers: 추가 요청 헤더 (선택 사항)

2. `send_post_webhook`

POST 방식으로 웹훅을 전송합니다.

매개변수:

url: 호출할 웹훅 URL (필수)
payload: 전송할 JSON 페이로드 (선택 사항)
headers: 요청 헤더 (선택 사항)
auth_token: 인증에 사용할 토큰 (선택 사항)

3. `send_custom_webhook`

사용자 지정 HTTP 메서드로 웹훅을 전송합니다.

매개변수:

method: HTTP 메서드 (GET, POST, PUT, DELETE, PATCH 등) (필수)
url: 호출할 웹훅 URL (필수)
payload: 전송할 JSON 페이로드 (선택 사항)
headers: 요청 헤더 (선택 사항)
auth_token: 인증에 사용할 토큰 (선택 사항)

프로젝트 구조

dante@webhook_trigger/
├── main.py                # MCP 서버 및 도구 정의
├── requirements.txt       # 종속성
├── run.sh                 # 실행 스크립트
├── mcp_run.sh             # MCP 서버 실행 스크립트 
└── .env                   # 환경 변수