# gcMeta-MCP

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
[![MCP](https://img.shields.io/badge/MCP-0.1.0-purple.svg)](https://modelcontextprotocol.io/)
[![Version](https://img.shields.io/badge/version-0.1.0-orange.svg)](https://github.com/zengzichao/gcMeta-MCP/releases)

> An MCP (Model Context Protocol) server that provides LLMs with access to the [gcMeta](https://gcmeta.wdcm.org/) (Global Catalogue of Metagenomics) platform.

**English** | [中文](./README_zh.md)

---

## 📋 Table of Contents

- [Overview](#overview)
- [Background](#background)
- [Features](#features)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
  - [Claude Desktop](#claude-desktop)
  - [Other MCP Clients](#other-mcp-clients)
  - [Direct Execution](#direct-execution)
- [Available Tools](#available-tools)
- [Development](#development)
- [Project Structure](#project-structure)
- [Documentation](#documentation)
- [Contributing](#contributing)
- [License](#license)
- [Citation](#citation)
- [Acknowledgements](#acknowledgements)

---

## Overview

**gcMeta-MCP** is a [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that bridges Large Language Models (LLMs) with the [gcMeta](https://gcmeta.wdcm.org/) — the **Global Catalogue of Metagenomics** platform maintained by [WDCM](https://www.wdcm.org/) / [NMDC](https://nmdc.cn/).

By exposing gcMeta's rich metagenomics data as MCP tools, this server enables LLM-powered assistants to search, retrieve, and analyze metagenomics data — including BioProjects, BioSamples, sequencing Runs, Metagenome-Assembled Genomes (MAGs), Biome Catalogues, Taxonomy Abundance, and Functional Annotations — all through natural language queries.

## Background

[gcMeta](https://gcmeta.wdcm.org/) is a global repository of metagenome-assembled genomes (MAGs) enabling cross-ecosystem microbial discovery and function research. As of 2026, it hosts:

| Metric | Count |
|--------|-------|
| Total MAGs | 3,917,189 |
| All MAGs under catalogues | 2,756,886 |
| Species-level representative MAGs | 109,586 |
| Runs | 177,196 |
| BioSamples | 127,760 |
| BioProjects | 9,653 |

The platform organizes MAGs into **50+ Biome Catalogues** spanning diverse ecosystems:

- **Human**: Gut, Skin, Vaginal
- **Animals**: Chicken, Pig, Cattle, Mouse, Cat, Dog, Horse, Goat, Sheep, etc.
- **Marine**: Seawater, Sediment
- **Freshwater**: Lake Water, Riverine, Sediment
- **Environments**: Agricultural Soil, Hot Spring, Permafrost, Wastewater, etc.
- **Extreme Environments**: Acid, Cold, Hot, Pressure, Saline-alkaline Habitats
- **Plant Rhizosphere**: Rice, Wheat, Arabidopsis, Bean
- **Wild Animals**: Bear, Deer, Elephant, Giant Panda, Koala, Vulture, etc.

gcMeta also provides **functional annotation** across several categories: Antibiotics Resistance Genes (ARGs), KEGG Pathways, Virulence Factors (VFs), Carbohydrate-Active enZYmes (CAZy), Biosynthetic Gene Clusters (BGCs), Mobile Genetic Elements (MGEs), and Defense Systems.

## Features

- 🔌 **MCP Protocol Support** — Full compatibility with the Model Context Protocol specification.
- 🧬 **13 Tools** — Search and retrieve BioProjects, BioSamples, Runs, MAGs, Biome Catalogues, Taxonomy Abundance, Functional Annotations, and platform statistics.
- 🌐 **Type-safe** — Written in TypeScript with Zod schema validation for all inputs.
- ⚡ **Lightweight** — Minimal dependencies, stdio-based transport, no external server required.
- 🔧 **Configurable** — Custom base URL, authentication token, and timeout settings.
- 📦 **Zero-config** — Works out of the box with `npx` or direct installation.

## Prerequisites

- **Node.js** >= 18.0.0
- An MCP-compatible client (e.g., [Claude Desktop](https://claude.ai/download), [Cursor](https://cursor.sh/), or any MCP client)

## Installation

### Option 1: Using npx (recommended — no installation needed)

```bash
npx gcmeta-mcp
```

### Option 2: Global installation

```bash
npm install -g gcmeta-mcp
gcmeta-mcp
```

### Option 3: Local development

```bash
git clone https://github.com/zengzichao/gcMeta-MCP.git
cd gcMeta-MCP
npm install
npm run build
npm start
```

## Configuration

The server reads configuration from environment variables:

| Variable | Description | Default |
|----------|-------------|---------|
| `GCMETA_BASE_URL` | Base URL of the gcMeta instance | `https://gcmeta.wdcm.org` |
| `GCMETA_AUTH_TOKEN` | Optional authentication token | _(none)_ |

Copy `.env.example` to `.env` and adjust as needed:

```bash
cp .env.example .env
```

## Usage

### Claude Desktop

Add the following to your Claude Desktop configuration file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "gcmeta": {
      "command": "npx",
      "args": ["-y", "gcmeta-mcp"]
    }
  }
}
```

For local development:

```json
{
  "mcpServers": {
    "gcmeta": {
      "command": "node",
      "args": ["/path/to/gcMeta-MCP/dist/index.js"]
    }
  }
}
```

### Other MCP Clients

This server uses **stdio transport**, making it compatible with any MCP-compliant client. Simply configure your client to run `npx -y gcmeta-mcp` as the server command.

### Direct Execution

```bash
# After installation or building from source
node dist/index.js

# With custom base URL
GCMETA_BASE_URL=https://gcmeta.wdcm.org node dist/index.js
```

## Available Tools

The server exposes 13 tools:

| # | Tool | Description |
|---|------|-------------|
| 1 | `search_bioprojects` | Search for BioProjects by keyword, organism, etc. |
| 2 | `get_bioproject` | Get detailed info about a single BioProject |
| 3 | `search_biosamples` | Search for BioSamples with multiple filters |
| 4 | `get_biosample` | Get detailed info about a single BioSample |
| 5 | `search_runs` | Search for sequencing Runs |
| 6 | `get_run` | Get detailed info about a single Run |
| 7 | `search_mags` | Search for Metagenome-Assembled Genomes (MAGs) |
| 8 | `get_mag` | Get detailed info about a single MAG |
| 9 | `list_biome_catalogues` | List all available biome catalogues |
| 10 | `get_biome_catalogue` | Get detailed info about a specific biome catalogue |
| 11 | `get_taxonomy_abundance` | Get taxonomy abundance for a sample or catalogue |
| 12 | `search_functional_annotations` | Search functional annotations (ARGs, KEGG, CAZy, etc.) |
| 13 | `get_statistics` | Get aggregate platform statistics |

See the [API Reference](./docs/en/API.md) for detailed input/output specifications of each tool.

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Lint
npm run lint

# Format
npm run format
```

## Project Structure

```
gcMeta-MCP/
├── src/
│   ├── index.ts            # Server entry point
│   ├── gcmeta-client.ts    # gcMeta HTTP API client
│   ├── tools.ts            # MCP tool definitions
│   └── types.ts            # TypeScript type definitions
├── docs/
│   ├── en/                 # English documentation
│   │   ├── INSTALLATION.md
│   │   ├── API.md
│   │   └── CONFIGURATION.md
│   └── zh/                 # Chinese documentation
│       ├── 安装指南.md
│       ├── API文档.md
│       └── 配置说明.md
├── examples/
│   └── claude-desktop-config.json
├── package.json
├── tsconfig.json
├── eslint.config.js
├── .prettierrc
├── .editorconfig
├── .env.example
├── .gitignore
├── LICENSE
├── README.md               # English (this file)
├── README_zh.md            # Chinese
├── CHANGELOG.md
├── CONTRIBUTING.md
└── CONTRIBUTING_zh.md
```

## Documentation

- [Installation Guide (EN)](./docs/en/INSTALLATION.md) | [安装指南 (中文)](./docs/zh/安装指南.md)
- [API Reference (EN)](./docs/en/API.md) | [API 文档 (中文)](./docs/zh/API文档.md)
- [Configuration (EN)](./docs/en/CONFIGURATION.md) | [配置说明 (中文)](./docs/zh/配置说明.md)
- [Changelog](./CHANGELOG.md)
- [Contributing (EN)](./CONTRIBUTING.md) | [贡献指南 (中文)](./CONTRIBUTING_zh.md)

## Contributing

Contributions are welcome! Please read the [Contributing Guide](./CONTRIBUTING.md) (中文: [贡献指南](./CONTRIBUTING_zh.md)) for details on how to submit pull requests, report issues, and suggest features.

## License

This project is licensed under the [MIT License](./LICENSE).

## Citation

If you use gcMeta-MCP in your research, please cite both the tool and the gcMeta platform:

```bibtex
@software{gcmeta-mcp,
  title  = {gcMeta-MCP: An MCP Server for the Global Catalogue of Metagenomics},
  author = {Zeng, Zichao},
  year   = {2026},
  version = {0.1.0},
  url    = {https://github.com/zengzichao/gcMeta-MCP}
}
```

## Acknowledgements

- [gcMeta](https://gcmeta.wdcm.org/) — Global Catalogue of Metagenomics, maintained by WDCM / NMDC
- [Model Context Protocol](https://modelcontextprotocol.io/) — The protocol specification
- [WDCM](https://www.wdcm.org/) — World Data Centre for Microorganisms
- [NMDC](https://nmdc.cn/) — National Microbiology Data Center