Oh My KEGG MCP

KEGG (Kyoto Encyclopedia of Genes and Genomes) 데이터베이스에 접근하기 위한 Model Context Protocol (MCP) 서버입니다.(unofficial)

주요 기능

• 30개의 KEGG 도구: 경로, 유전자, 화합물, 반응, 효소, 질병, 약물 등 다양한 생물학적 데이터 검색 및 분석
• Streamable HTTP Transport: 웹 환경에서 사용 가능한 HTTP 기반 통신
• LangChain 통합: LangChain Agent와 완벽하게 통합되어 LLM이 KEGG 데이터를 활용할 수 있음
• Ollama 지원: 로컬 LLM 모델과 함께 사용 가능

설치

1. 필수 패키지 설치

pip install -r requirements.txt

2. 환경 변수 설정

.env.example 파일을 참고하여 .env 파일을 생성합니다:

cp .env.example .env

.env 파일을 편집하여 필요한 값을 설정합니다:

# OpenAI API 키 (OpenAI 모델 사용 시 필요)
# Ollama 사용 시에는 설정하지 않아도 됩니다
OPENAI_API_KEY=your_openai_api_key

# MCP 서버 URL (클라이언트에서 사용)
# 서버가 다른 호스트/포트에서 실행되는 경우 변경
KEGG_MCP_SERVER_URL=http://localhost:3000/mcp

# MCP 서버 설정 (서버 실행 시 사용, 선택사항)
# 기본값이 설정되어 있어 변경하지 않아도 됩니다
MCP_HOST=localhost
MCP_PORT=3000
MCP_PATH=/mcp

# Ollama 설정 (선택사항)
# Ollama가 다른 호스트/포트에서 실행되는 경우 변경
# OLLAMA_HOST=http://localhost:11434

참고:

• Ollama 사용 시: OPENAI_API_KEY는 설정하지 않아도 됩니다. 현재 코드는 Ollama를 기본 모델로 사용합니다.
• OpenAI 사용 시: OPENAI_API_KEY에 실제 API 키를 설정하고, langchain_integration.py에서 ChatOpenAI를 사용하도록 변경해야 합니다.
• 서버 설정: MCP_HOST, MCP_PORT, MCP_PATH는 서버 실행 시 사용되며, 기본값이 설정되어 있어 변경하지 않아도 됩니다.
• Ollama 호스트: Ollama가 기본 포트(11434)가 아닌 다른 포트에서 실행되는 경우 OLLAMA_HOST를 설정할 수 있습니다.

사용 방법

1. 서버 실행

# 기본 설정으로 실행 (localhost:3000/mcp)
python kegg_mcp_server.py

# 또는 환경 변수로 설정
MCP_HOST=localhost MCP_PORT=3000 MCP_PATH=/mcp python kegg_mcp_server.py

서버가 실행되면 다음과 같은 메시지가 표시됩니다:

Starting KEGG MCP Server on http://localhost:3000/mcp
Transport: Streamable HTTP

2. 클라이언트 실행

# 기본 실행 (Streamable HTTP 사용)
python langchain_integration.py

# Ollama 연결 테스트만 실행
python langchain_integration.py --test

# stdio 사용 (선택사항, 별도 TypeScript 서버 필요)
# langchain_integration.py에서 use_http=False로 변경
# 참고: 현재는 Streamable HTTP 방식만 제공됩니다

사용 가능한 도구

Database Information & Statistics (2개)

• get_database_info - 데이터베이스 정보 및 통계 조회
• list_organisms - 모든 KEGG 생물체 목록 조회

Pathway Analysis (3개)

• search_pathways - 경로 검색
• get_pathway_info - 경로 상세 정보
• get_pathway_genes - 경로의 유전자 목록

Gene Analysis (2개)

• search_genes - 유전자 검색
• get_gene_info - 유전자 상세 정보 (서열 포함 옵션)

Compound Analysis (2개)

• search_compounds - 화합물 검색
• get_compound_info - 화합물 상세 정보

Reaction & Enzyme Analysis (4개)

• search_reactions - 반응 검색
• get_reaction_info - 반응 상세 정보
• search_enzymes - 효소 검색
• get_enzyme_info - 효소 상세 정보

Disease & Drug Analysis (5개)

• search_diseases - 질병 검색
• get_disease_info - 질병 상세 정보
• search_drugs - 약물 검색
• get_drug_info - 약물 상세 정보
• get_drug_interactions - 약물 상호작용 조회

Module & Orthology Analysis (4개)

• search_modules - 모듈 검색
• get_module_info - 모듈 상세 정보
• search_ko_entries - KO 엔트리 검색
• get_ko_info - KO 상세 정보

Glycan Analysis (2개)

• search_glycans - 글리칸 검색
• get_glycan_info - 글리칸 상세 정보

BRITE Hierarchy Analysis (2개)

• search_brite - BRITE 계층 검색
• get_brite_info - BRITE 상세 정보

Advanced Analysis Tools (5개)

• get_pathway_compounds - 경로의 화합물 목록
• get_pathway_reactions - 경로의 반응 목록
• get_compound_reactions - 화합물의 반응 목록
• get_gene_orthologs - 유전자 직계동족 찾기
• batch_entry_lookup - 배치 엔트리 조회

Cross-References & Integration (2개)

• convert_identifiers - 데이터베이스 간 식별자 변환
• find_related_entries - 관련 엔트리 찾기

예제

기본 사용 예제

import asyncio
from langchain_integration import create_kegg_client, load_and_display_tools, create_default_model, run_agent_query
from langchain.agents import create_agent

async def main():
    # 클라이언트 생성 (Streamable HTTP)
    client = create_kegg_client()
    
    try:
        # 도구 로드
        tools = await load_and_display_tools(client)
        
        # 모델 및 Agent 생성
        model = create_default_model()
        agent = create_agent(model=model, tools=tools)
        
        # 쿼리 실행
        await run_agent_query(
            agent,
            "인간의 당분해(glycolysis) 경로를 찾아주세요.",
            "당분해 경로 검색"
        )
    finally:
        if hasattr(client, 'close'):
            try:
                await client.close()
            except:
                pass

if __name__ == "__main__":
    asyncio.run(main())

프로젝트 구조

kegg-mcp-test/
├── kegg_mcp_server.py          # Python MCP 서버 (Streamable HTTP)
├── langchain_integration.py    # LangChain 통합 클라이언트
├── requirements.txt             # Python 패키지 의존성
├── .env.example                # 환경 변수 예제 파일
├── .gitignore                  # Git 무시 파일 목록
├── LICENSE                     # MIT 라이선스
└── README.md                    # 프로젝트 문서 (이 파일)

통신 방식

Streamable HTTP (권장)

• 장점: 웹 환경 지원, 확장성 좋음, 표준 HTTP 프로토콜
• 사용: Python 서버 (kegg_mcp_server.py)
• 포트: 기본 3000 (환경 변수로 변경 가능)

stdio (로컬 전용, 선택사항)

• 장점: 최고의 보안, 낮은 오버헤드, 간단한 설정
• 사용: langchain_integration.py에서 use_http=False로 설정 시 사용 가능
• 제한: 로컬 실행만 가능, 별도 TypeScript 서버 필요

문제 해결

서버가 시작되지 않는 경우

1. 포트가 이미 사용 중인지 확인: lsof -i :3000
2. 필요한 패키지가 설치되었는지 확인: pip install -r requirements.txt
3. Python 버전 확인: Python 3.11 이상 필요

클라이언트 연결 실패

1. 서버가 실행 중인지 확인
2. 서버 URL이 올바른지 확인: KEGG_MCP_SERVER_URL 환경 변수
3. 방화벽 설정 확인

Ollama 연결 실패

1. Ollama가 실행 중인지 확인: ollama serve
2. 모델이 설치되었는지 확인: ollama list
3. 모델 다운로드: ollama pull gemma3:4b (또는 사용할 모델)

라이선스

MIT License

참고 자료

• KEGG REST API 문서
• Model Context Protocol
• LangChain 문서
• FastMCP 문서