phddy/kiwi-mcp-server

Kiwi MCP Server

한국어 형태소 분석기 Kiwi를 Model Context Protocol (MCP) 서버로 제공하는 프로젝트입니다.

AI 에이전트(Claude 등)가 한국어 텍스트를 정확하게 분석하고 처리할 수 있도록 도와줍니다.

기능

1. analyze - 형태소 분석

한국어 텍스트를 형태소 단위로 분석하고 품사 태깅을 수행합니다.

입력:

• text (필수): 분석할 한국어 텍스트
• pos (선택): 필터링할 품사 태그 배열

예시:

{
  "text": "안녕하세요. 오늘 날씨가 좋네요.",
  "pos": ["NNG", "VA"]
}

2. similarity - 텍스트 유사도 측정

두 텍스트 간의 코사인 유사도를 계산합니다.

입력:

• text (필수): 첫 번째 비교할 텍스트
• text2 (필수): 두 번째 비교할 텍스트
• pos (선택): 유사도 계산 시 사용할 품사 태그

예시:

{
  "text": "오늘 날씨가 좋습니다",
  "text2": "날씨가 정말 좋네요",
  "pos": ["NNG", "VA"]
}

지원 품사 태그

체언

• NNG: 일반 명사
• NNP: 고유 명사
• NNB: 의존 명사
• NR: 수사
• NP: 대명사

용언

• VV: 동사
• VA: 형용사
• VX: 보조 용언
• VCP: 긍정 지정사
• VCN: 부정 지정사

기타

• MAG, MAJ: 부사
• MM: 관형사
• IC: 감탄사
• JKS, JKC, JKG, JKO, JKB, JKV, JKQ, JX, JC: 조사
• EP, EF, EC, ETN, ETM: 어미
• XPN, XSN, XSV, XSA, XSM, XR: 접사/어근
• SF, SP, SS, SE, SO, SW: 기호
• W_URL, W_EMAIL, W_HASHTAG, W_MENTION: 웹 관련

전체 품사 태그 목록

빠른 시작

Docker로 실행

# 최신 버전
docker run -p 5100:5100 phddy/kiwi-mcp-server:latest

# 특정 버전
docker run -p 5100:5100 phddy/kiwi-mcp-server:0.21.0

로컬 개발 환경

요구사항

• Go 1.24.7+
• Kiwi 라이브러리 (0.21.0)
• GCC/G++ (CGO 빌드용)

테스트

go test ./...

Docker 빌드

# 로컬 빌드
docker build -t kiwi-mcp-server .

# 멀티아키텍처 빌드
docker buildx build --platform linux/amd64,linux/arm64 -t kiwi-mcp-server .

MCP 클라이언트 설정

Claude Desktop 설정

서버를 실행한 후, Claude Desktop의 설정 파일에 다음 내용을 추가하세요.

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

{
  "mcpServers": {
    "kiwi": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://localhost:5100/sse"
      ]
    }
  }
}

사용 예시

Claude Desktop에서 다음과 같이 사용할 수 있습니다:

"안녕하세요"를 형태소 분석해줘

"오늘 날씨가 좋다"와 "날씨가 정말 좋네요"의 유사도를 측정해줘

"서울특별시"를 명사만 추출해서 분석해줘

Docker Compose로 실행

지속적으로 서버를 실행하려면 Docker Compose를 사용하세요:

# docker-compose.yml
version: '3.8'
services:
  kiwi-mcp:
    image: phddy/kiwi-mcp-server:latest
    ports:
      - "5100:5100"
    restart: unless-stopped

docker-compose up -d

환경 변수

• KIWI_MODEL_PATH: Kiwi 모델 파일 경로 (기본값: /usr/share/kiwi/models/base)

관련 링크

• Kiwi 한국어 형태소 분석기
• Kiwi GO Wrapper
• MCP Go SDK