국립국어원 표준국어대사전 MCP 서버

국립국어원 표준국어대사전 API를 MCP(Model Context Protocol) 서버로 제공하는 TypeScript 패키지입니다.

소개

이 프로젝트는 국립국어원 표준국어대사전 오픈 API를 MCP(Model Context Protocol) 서버로 변환하여 제공합니다. Claude, ChatGPT 등 대규모 언어 모델(LLM)이 한국어 사전 정보에 접근하고 활용할 수 있도록 도와줍니다.

설치

NPM을 통해 설치할 수 있습니다:

# 전역 설치
npm install -g koreandict-mcp-server

# 로컬 프로젝트에 설치
npm install koreandict-mcp-server

설정

서버를 실행하기 전에 국립국어원에서 발급받은 API 키를 설정해야 합니다. 다음 두 가지 방법 중 하나를 선택할 수 있습니다:

1. 환경 변수 사용

.env 파일을 생성하고 API 키를 설정합니다:

KOREANDICT_API_KEY=your-api-key-here

2. MCP 설정 파일 사용

mcp.json 파일을 생성하고 다음과 같이 설정합니다:

{
  "koreandict-server": {
    "command": "node",
    "args": [
      "./dist/index.js"
    ],
    "env": {
      "KOREANDICT_API_KEY": "your-api-key-here"
    }
  }
}

이 설정 파일은 현재 디렉토리나 홈 디렉토리의 .cursor/mcp.json에 위치할 수 있습니다.

사용 방법

직접 실행

패키지를 전역으로 설치한 경우 명령줄에서 다음과 같이 실행할 수 있습니다:

koreandict-mcp-server

프로그래밍 방식으로 사용

프로젝트에 패키지를 설치한 경우 다음과 같이 코드에서 사용할 수 있습니다:

import { KoreanDictionaryMcpServer } from 'koreandict-mcp-server';

// 서버 인스턴스 생성
const server = new KoreanDictionaryMcpServer();

// 서버 시작
server.getServer().listen();

MCP 클라이언트에서 사용

MCP 클라이언트(예: Cursor)에서 사용하려면, 클라이언트의 MCP 설정에 서버 정보를 추가합니다. 대부분의 경우 ~/.cursor/mcp.json 파일을 수정해야 합니다:

{
  "koreandict-server": {
    "command": "koreandict-mcp-server",
    "env": {
      "KOREANDICT_API_KEY": "your-api-key-here"
    }
  }
}

기능

MCP 리소스

• koreandict://word/{word} - 단어 검색 결과를 제공합니다.
• koreandict://pos/{pos}/word/{word} - 품사별 단어 검색 결과를 제공합니다.

MCP 도구

• search-word - 단어를 검색합니다. 검색 방식과 결과 개수를 지정할 수 있습니다.
• search-by-pos - 품사별로 단어를 검색합니다.

개발

저장소 클론

# 저장소 클론
git clone https://github.com/tenacl/koreandict-mcp-server.git
cd koreandict-mcp-server

# 의존성 설치
npm install

# 개발 서버 실행
npm run dev

# 빌드
npm run build

테스트

npm test

문제 해결

MCP 연결 오류

MCP 연결 오류가 발생할 경우 다음을 확인하세요:

1. API 키가 올바르게 설정되어 있는지 확인
2. mcp.json 파일의 경로 설정이 올바른지 확인
3. 로그에 나타나는 오류 메시지 확인

기여하기

이슈와 풀 리퀘스트는 GitHub 저장소를 통해 제출해주세요.

라이선스

MIT

참고 자료

• 국립국어원 표준국어대사전
• Model Context Protocol
• MCP TypeScript SDK