oh-my-kegg-mcp

# Oh My KEGG MCP KEGG (Kyoto Encyclopedia of Genes and Genomes) database Model Context Protocol (MCP) server. (unofficial) ## Key Features - **30 KEGG Tools**: Search and analyze various biological data such as pathways, genes, compounds, reactions, enzymes, diseases, and drugs - **Streamable HTTP Transport**: HTTP-based communication available in web environments - **LangChain Integration**: Seamlessly integrated with LangChain Agent, allowing LLMs to utilize KEGG data - **Ollama Support**: Can be used with local LLM models ## Installation ### 1. Install Required Packages ```bash pip install -r requirements.txt ``` ### 2. Configure Environment Variables Create a `.env` file by referring to the `.env.example` file: ```bash cp .env.example .env ``` Edit the `.env` file to set the necessary values: ```bash # OpenAI API Key (Required when using OpenAI models) # Not required when using Ollama OPENAI_API_KEY=your_openai_api_key # MCP Server URL (Used by the client) # Change if the server is running on a different host/port KEGG_MCP_SERVER_URL=http://localhost:3000/mcp # MCP Server Configuration (Used when running the server, optional) # Default values are set, so you don't need to change them MCP_HOST=localhost MCP_PORT=3000 MCP_PATH=/mcp # Ollama Configuration (Optional) # Change if Ollama is running on a different host/port # OLLAMA_HOST=http://localhost:11434 ``` **Note**: - **When using Ollama**: `OPENAI_API_KEY` does not need to be set. The current code uses Ollama as the default model. - **When using OpenAI**: You must set the actual API key in `OPENAI_API_KEY` and change `langchain_integration.py` to use `ChatOpenAI`. - **Server Configuration**: `MCP_HOST`, `MCP_PORT`, and `MCP_PATH` are used when running the server, and default values are set, so you don't need to change them. - **Ollama Host**: You can set `OLLAMA_HOST` if Ollama is running on a port other than the default port (11434). ## Usage ### 1. Run the Server ```bash # Run with default settings (localhost:3000/mcp) python kegg_mcp_server.py # Or set with environment variables MCP_HOST=localhost MCP_PORT=3000 MCP_PATH=/mcp python kegg_mcp_server.py ``` When the server is running, the following message is displayed: ``` Starting KEGG MCP Server on http://localhost:3000/mcp Transport: Streamable HTTP ``` ### 2. Run the Client ```bash # Basic execution (using Streamable HTTP) python langchain_integration.py # Run only the Ollama connection test python langchain_integration.py --test # Use stdio (optional, requires a separate TypeScript server) # Change use_http=False in langchain_integration.py # Note: Currently, only Streamable HTTP is provided ``` ## Available Tools ### Database Information & Statistics (2 tools) - `get_database_info` - Retrieve database information and statistics - `list_organisms` - Retrieve a list of all KEGG organisms ### Pathway Analysis (3 tools) - `search_pathways` - Search pathways - `get_pathway_info` - Get detailed pathway information - `get_pathway_genes` - Get a list of genes in the pathway ### Gene Analysis (2 tools) - `search_genes` - Search genes - `get_gene_info` - Get detailed gene information (including sequence option) ### Compound Analysis (2 tools) - `search_compounds` - Search compounds - `get_compound_info` - Get detailed compound information ### Reaction & Enzyme Analysis (4 tools) - `search_reactions` - Search reactions - `get_reaction_info` - Get detailed reaction information - `search_enzymes` - Search enzymes - `get_enzyme_info` - Get detailed enzyme information ### Disease & Drug Analysis (5 tools) - `search_diseases` - Search diseases - `get_disease_info` - Get detailed disease information - `search_drugs` - Search drugs - `get_drug_info` - Get detailed drug information - `get_drug_interactions` - Retrieve drug interactions ### Module & Orthology Analysis (4 tools) - `search_modules` - Search modules - `get_module_info` - Get detailed module information - `search_ko_entries` - Search KO entries - `get_ko_info` - Get detailed KO information ### Glycan Analysis (2 tools) - `search_glycans` - Search glycans - `get_glycan_info` - Get detailed glycan information ### BRITE Hierarchy Analysis (2 tools) - `search_brite` - Search BRITE hierarchy - `get_brite_info` - Get detailed BRITE information ### Advanced Analysis Tools (5 tools) - `get_pathway_compounds` - Get a list of compounds in the pathway - `get_pathway_reactions` - Get a list of reactions in the pathway - `get_compound_reactions` - Get a list of reactions for the compound - `get_gene_orthologs` - Find gene orthologs - `batch_entry_lookup` - Batch entry lookup ### Cross-References & Integration (2 tools) - `convert_identifiers` - Convert identifiers between databases - `find_related_entries` - Find related entries ## Examples ### Basic Usage Example ```python 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(): # Create a client (Streamable HTTP) client = create_kegg_client() try: # Load tools tools = await load_and_display_tools(client) # Create a model and Agent model = create_default_model() agent = create_agent(model=model, tools=tools) # Execute query await run_agent_query( agent, "인간의 당분해(glycolysis) 경로를 찾아주세요.", "당분해 경로 검색" ) finally: if hasattr(client, 'close'): try: await client.close() except: pass if __name__ == "__main__": asyncio.run(main()) ``` ## Project Structure ``` kegg-mcp-test/ ├── kegg_mcp_server.py # Python MCP Server (Streamable HTTP) ├── langchain_integration.py # LangChain Integration Client ├── requirements.txt # Python Package Dependencies ├── .env.example # Example Environment Variable File ├── .gitignore # Git Ignore File List ├── LICENSE # MIT License └── README.md # Project Documentation (This File) ``` ## Communication Method ### Streamable HTTP (Recommended) - **Advantages**: Web environment support, good scalability, standard HTTP protocol - **Usage**: Python server (`kegg_mcp_server.py`) - **Port**: Default 3000 (can be changed with environment variables) ### stdio (Local Only, Optional) - **Advantages**: Best security, low overhead, simple setup - **Usage**: Can be used by setting `use_http=False` in `langchain_integration.py` - **Limitations**: Local execution only, requires a separate TypeScript server ## Troubleshooting ### If the server does not start 1. Check if the port is already in use: `lsof -i :3000` 2. Check if the required packages are installed: `pip install -r requirements.txt` 3. Check the Python version: Python 3.11 or higher is required ### Client connection failed 1. Check if the server is running 2. Check if the server URL is correct: `KEGG_MCP_SERVER_URL` environment variable 3. Check firewall settings ### Ollama connection failed 1. Check if Ollama is running: `ollama serve` 2. Check if the model is installed: `ollama list` 3. Download the model: `ollama pull gemma3:4b` (or the model to use) ## License MIT License ## References - [KEGG REST API Documentation](https://www.kegg.jp/kegg/rest/keggapi.html) - [Model Context Protocol](https://modelcontextprotocol.io) - [LangChain Documentation](https://python.langchain.com) - [FastMCP Documentation](https://github.com/jlowin/fastmcp)