다라자 MCP

AI 애플리케이션을 Safaricom의 Daraja API와 통합하도록 설계된 MCP(Model Context Protocol) 서버로, M-Pesa 서비스와의 원활한 상호작용을 지원합니다.

⚠️ 경고: 생산 준비가 되지 않았습니다
이 프로젝트는 현재 개발 중이며 프로덕션 용도로는 권장되지 않습니다. 다음 용도로 설계되었습니다.
학습과 실험
개발 및 테스트 환경
개념 증명 구현
생산용으로 사용하려면 다음 사항을 확인하세요.
철저한 보안 테스트
적절한 오류 처리
계획된 모든 기능의 완전한 구현
Safaricom의 생산 요구 사항 준수

MCP 서버란 무엇인가요?

MCP(Model Context Protocol) 서버는 LLM이 외부 시스템과 상호 작용할 수 있는 기능을 제공합니다. MCP 서버는 세 가지 주요 기능을 제공할 수 있습니다.

리소스 : 클라이언트가 읽을 수 있는 파일형 데이터(API 응답 등)
도구 : LLM에서 호출할 수 있는 기능(사용자 승인 필요)
프롬프트 : 사용자가 특정 작업을 수행하는 데 도움이 되는 미리 작성된 템플릿

Daraja MCP는 특히 이 아키텍처를 활용하여 AI 시스템을 Safaricom의 Daraja M-Pesa API에 연결합니다.

개요

Daraja MCP는 AI, 핀테크, 그리고 M-Pesa를 연결하는 다리 역할을 하며, AI 기반 금융 자동화의 접근성과 효율성을 높여줍니다. Daraja MCP는 LLM(대규모 언어 모델)과 금융 거래 간의 연결을 표준화함으로써 AI 기반 애플리케이션이 결제를 처리하고, 거래 데이터를 검색하고, 금융 워크플로를 손쉽게 자동화할 수 있도록 지원합니다.

주요 역량

✅ AI 기반 M-Pesa 거래 – LLM이 B2C, C2B 및 B2B 결제를 처리할 수 있도록 지원
✅ 표준화된 통합 – MCP는 여러 AI 도구와의 호환성을 보장합니다.
✅ 안전하고 확장 가능 – OAuth 인증을 구현하고 엔터프라이즈급 트랜잭션 처리를 지원합니다.
✅ 유연한 자동화 – AI 에이전트는 계정 잔액을 쿼리하고, 송장을 생성하고, 조정을 자동화할 수 있습니다.

요구 사항

파이썬 3.12
Safaricom Daraja API 자격 증명(소비자 키 및 비밀)

설치

1단계: 환경 설정

uv 패키지 관리자 설치Mac/Linux의 경우:지엑스피1Windows(PowerShell)의 경우:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
저장소 복제
git clone https://github.com/jameskanyiri/DarajaMCP.git cd DarajaMCP
가상 환경 생성 및 활성화
uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate
✅ 예상 출력: 터미널 프롬프트가 변경되어 가상 환경이 활성화되었음을 나타냅니다.
종속성 설치
uv sync

2단계: 환경 변수 설정

예제 환경 파일을 복사하세요.
cp .env.example .env
실제 자격 증명과 구성 값으로 .env 파일을 업데이트합니다.

참고: 개발 환경에서는 샌드박스 환경을 사용하세요. 준비가 되면 프로덕션 URL로 전환하세요.

용법

Claude Desktop으로 테스트

Claude Desktop 설치
- Claude Desktop 에서 최신 버전을 다운로드하고 설치하세요.
- 최신 버전을 실행하고 있는지 확인하세요
Claude Desktop 구성
- Claude Desktop 구성 파일을 엽니다.
  # On MacOS/Linux code ~/Library/Application\ Support/Claude/claude_desktop_config.json # On Windows code %APPDATA%\Claude\claude_desktop_config.json
- 파일이 존재하지 않으면 생성합니다.
서버 구성 추가 다음 구성 중 하나를 선택하세요.

Anthropic의 권장 형식

{
  "mcpServers": {
    "daraja": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/DarajaMCP",
        "run",
        "main.py"
      ]
    }
  }
}

작동 구성(테스트됨)

{
  "mcpServers": {
    "DarajaMCP": {
      "command": "/ABSOLUTE/PATH/TO/PARENT/.local/bin/uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/DarajaMCP",
        "run",
        "main.py"
      ]
    }
  }
}

메모:
/ABSOLUTE/PATH/TO/PARENT 실제 경로로 바꾸세요.
uv 의 전체 경로를 찾으려면 다음을 실행하세요.

# On MacOS/Linux
which uv

# On Windows
where uv

구성 확인
- 구성 파일을 저장합니다
- Claude Desktop을 다시 시작하세요
- 인터페이스에서 망치 🔨 아이콘을 찾으세요.
- 클릭하면 사용 가능한 도구를 볼 수 있습니다.
  - 액세스 토큰 생성
  - stk_push (향후 구현)
  - query_transaction_status(향후 구현)
  - b2c_payment (향후 구현)
  - account_balance (향후 구현)

도구 및 프롬프트

결제 도구

stk_push

M-Pesa STK 푸시 요청을 시작하여 고객에게 모바일 기기에서 결제를 승인하도록 요청합니다.

입력:

amount (int): 지불해야 할 금액
phone_number (int): 고객의 전화번호

반환: JSON 형식의 M-PESA API 응답

QR코드 생성

고객이 결제를 위해 스캔할 수 있는 결제 요청에 대한 QR 코드를 생성합니다.

입력:

merchant_name (str): 회사 이름/M-Pesa 가맹점 이름
transaction_reference_no (str): 거래 참조 번호
amount (int): 판매/거래 총액
transaction_type (Literal["BG", "WA", "PB", "SM", "SB"]): 거래 유형
credit_party_identifier (str): 신용 당사자 식별자(휴대폰 번호, 사업자 번호, 대리점 계산대, 지불서 또는 판매자 구매 상품)

반환: QR 코드 데이터가 포함된 JSON 형식의 M-PESA API 응답

결제 프롬프트

stk_push_prompt

M-Pesa STK 푸시 결제 요청을 시작하기 위한 메시지를 생성합니다.

입력:

phone_number (str): 고객의 전화번호
amount (int): 지불해야 할 금액
purpose (str): 결제 목적

반환: STK 푸시 요청에 대한 형식화된 프롬프트 문자열

QR코드 프롬프트 생성

M-Pesa QR 코드 결제 요청을 생성하기 위한 메시지를 생성합니다.

입력:

merchant_name (str): 상인/사업체 이름
amount (int): 지불해야 할 금액
transaction_type (str): 거래 유형(BG는 상품 구매, WA는 지갑, PB는 지불서, SM은 송금, SB는 사업체로 송금)
identifier (str): 수신자 식별자(계산대 번호, 납부서, 전화번호)
reference (str, 선택 사항): 거래 참조 번호입니다. 지정하지 않으면 기본값이 사용됩니다.

반환: QR 코드 생성을 위한 형식화된 프롬프트 문자열

문서 처리 도구

소스 생성

처리를 위해 데이터 소스에서 비정형 서버로 연결되는 커넥터를 만듭니다.

입력:

connector_name (str): 생성할 소스 커넥터의 이름

반환: 이름 및 ID를 포함한 소스 커넥터 세부 정보

목적지 생성

비정형 서버에서 데이터 저장 대상까지 커넥터를 만듭니다.

입력:

connector_name (str): 생성할 대상 커넥터의 이름

반환: 이름 및 ID를 포함한 대상 커넥터 세부 정보

워크플로우 생성

소스 커넥터에서 대상 커넥터로 데이터를 처리하는 워크플로를 만듭니다.

입력:

workflow_name (str): 생성할 워크플로의 이름
source_id (str): 소스 커넥터의 ID
destination_id (str): 대상 커넥터의 ID

반환: 이름, ID, 상태, 유형, 소스, 대상 및 일정을 포함한 워크플로 세부 정보

실행_워크플로

워크플로를 실행합니다.

입력:

workflow_id (str): 실행할 워크플로의 ID

반환: 워크플로 실행 상태

워크플로우 세부 정보 가져오기

워크플로에 대한 자세한 정보를 얻으세요.

입력:

workflow_id (str): 세부 정보를 가져올 워크플로의 ID

반환: 이름, ID, 상태를 포함한 워크플로 세부 정보

페치_문서

워크플로 실행 중에 분석된 문서를 가져옵니다.

입력: 없음

반환: 분석된 문서 목록

프롬프트

워크플로 프롬프트 생성 및 실행

문서 처리를 위한 워크플로를 만들고 실행하기 위한 프롬프트를 생성합니다.

입력:

user_input (str): 사용자의 처리 요구 사항

반환: 워크플로 생성 및 실행을 위한 형식화된 프롬프트

예:

# Example usage
prompt = await create_and_run_workflow_prompt(
    user_input="Process all PDF invoices from the invoices folder and store them in the processed folder"
)
# Returns: "The user wants to achieve Process all PDF invoices from the invoices folder and store them in the processed folder. Assist them by creating a source connector and a destination connector, then setting up the workflow and executing it."

자원

현재는 이용 가능한 리소스가 없습니다.

특허

MIT 라이센스

감사의 말

Daraja API를 제공해준 Safaricom
MCP 프레임워크를 위한 Anthropic
프로젝트 기여자

연락하다

문의사항이 있으시면 GitHub 저장소에서 이슈를 열어주세요.

Integrations

다라자 MCP

MCP 서버란 무엇인가요?

개요

주요 역량

요구 사항

설치

1단계: 환경 설정

2단계: 환경 변수 설정

용법

Claude Desktop으로 테스트

Anthropic의 권장 형식

작동 구성(테스트됨)

도구 및 프롬프트

결제 도구

stk_push

QR코드 생성

결제 프롬프트

stk_push_prompt

QR코드 프롬프트 생성

문서 처리 도구

소스 생성

목적지 생성

워크플로우 생성

실행_워크플로

워크플로우 세부 정보 가져오기

페치_문서

프롬프트

워크플로 프롬프트 생성 및 실행

자원

특허

감사의 말

연락하다