# NMDC-MCP

> MCP (Model Context Protocol) Server for the [National Microbiology Data Center (NMDC)](https://nmdc.cn/) of China.

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-0.1.0-green.svg)](https://modelcontextprotocol.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Version](https://img.shields.io/badge/version-0.1.0-orange.svg)]()

## Overview

NMDC-MCP is a Model Context Protocol (MCP) server that provides AI applications with access to the data and services of the **National Microbiology Data Center (NMDC)** — China's national-level data center for microbiology research. The server exposes NMDC's rich data resources through a standardized MCP interface, enabling AI assistants like Claude, ChatGPT, and others to search, query, and explore microbiology data.

### What is NMDC?

The [National Microbiology Data Center](https://nmdc.cn/) (国家微生物科学数据中心) is hosted by the Institute of Microbiology, Chinese Academy of Sciences. It provides comprehensive microbiology data services including:

- **Microbiome Data** — BioProjects, BioSamples, Nucleotides, Metagenomes, Genomes, Proteins, SRA, and more
- **Microbial Resources** — Global Catalogue of Microorganisms (GCM), biological parts
- **Virus Data** — Virus pathogen sequences, SARS-CoV-2 genome and variation data
- **Pathogen Data** — Pathogen catalogues, plasmids, phage, tuberculosis data
- **Fungi Data** — Fungal names, genomes, type specimens
- **Microbial Dictionary** — Biological terms, DNA barcodes
- **Microbial Catalog** — Global microbial names, Chinese fungal specimens

### What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io/) is an open standard for connecting AI applications to external systems. It provides a unified way for AI assistants to access data sources, tools, and workflows.

## Features

- 🔬 **19 MCP Tools** covering all major NMDC data categories
- 📚 **5 MCP Resources** for structured data access
- 🔄 **Resource Templates** for dynamic URI-based access
- 🌐 **Async HTTP Client** for efficient NMDC API communication
- ⚙️ **Configurable** via environment variables
- 📦 **Easy Installation** via pip or uv

## Quick Start

### Installation

```bash
# Using pip
pip install nmdc-mcp

# Or using uv
uv pip install nmdc-mcp

# Or from source
git clone https://github.com/zengzichao/NMDC-MCP.git
cd NMDC-MCP
pip install -e .
```

### Configuration

Add the NMDC-MCP server to your MCP client configuration:

#### Claude Desktop / Claude Code

```json
{
  "mcpServers": {
    "nmdc": {
      "command": "nmdc-mcp",
      "env": {
        "NMDC_BASE_URL": "https://nmdc.cn"
      }
    }
  }
}
```

#### Cursor / VS Code

```json
{
  "mcp.servers": {
    "nmdc": {
      "command": "nmdc-mcp"
    }
  }
}
```

### Usage

Once configured, you can ask your AI assistant to interact with NMDC data:

```
Search NMDC for E. coli genome data
What analysis tools are available on NMDC?
Look up the BioProject PRJCA000001 on NMDC
Search the microbial dictionary for "bacteriophage"
```

## Available Tools

| Tool | Description |
|------|-------------|
| `search_nmdc_data` | Search across all NMDC databases by keyword |
| `get_nmdc_data_overview` | Get overview of all available data resources |
| `get_bioproject` | Get BioProject details by accession ID |
| `get_biosample` | Get BioSample details by accession ID |
| `get_sequence` | Get sequence information by accession ID |
| `search_genome` | Search genome records |
| `search_sra` | Search Sequence Read Archive data |
| `search_metagenome` | Search metagenome data |
| `search_virus` | Search virus pathogen data |
| `search_ncov_variation` | Search SARS-CoV-2 variation data |
| `search_fungi` | Search fungi microorganism data |
| `search_pathogen` | Search pathogen microorganism data |
| `search_tuberculosis` | Search tuberculosis data |
| `search_gcm` | Search Global Catalogue of Microorganisms |
| `search_microbial_dictionary` | Search microbial dictionary for terms |
| `search_microbial_catalog` | Search microbial catalog |
| `get_analysis_tools` | Get available analysis tools |
| `get_metadata_standards` | Get metadata standards information |
| `get_download_list` | Get downloadable dataset list |

## Configuration Options

| Environment Variable | Default | Description |
|---------------------|---------|-------------|
| `NMDC_BASE_URL` | `https://nmdc.cn` | NMDC website base URL |
| `NMDC_API_BASE_URL` | `https://nmdc.cn/api` | NMDC API base URL |
| `NMDC_TIMEOUT` | `30.0` | HTTP request timeout (seconds) |
| `NMDC_MAX_RESULTS` | `50` | Maximum results per query |
| `NMDC_PAGE_SIZE` | `20` | Default page size for pagination |

## Development

### Setup Development Environment

```bash
git clone https://github.com/zengzichao/NMDC-MCP.git
cd NMDC-MCP
pip install -e ".[dev]"
```

### Run Tests

```bash
pytest
```

### Lint and Type Check

```bash
ruff check src/
mypy src/
```

## Documentation

- [English Documentation](docs/en/)
  - [Installation Guide](docs/en/installation.md)
  - [Usage Guide](docs/en/usage.md)
  - [Tools Reference](docs/en/tools.md)
  - [Configuration Guide](docs/en/configuration.md)
  - [Architecture](docs/en/architecture.md)
  - [Development Guide](docs/en/development.md)
  - [API Reference](docs/en/api.md)
  - [FAQ](docs/en/faq.md)
  - [Changelog](docs/en/changelog.md)

- [中文文档](docs/zh/)
  - [安装指南](docs/zh/installation.md)
  - [使用指南](docs/zh/usage.md)
  - [工具参考](docs/zh/tools.md)
  - [配置指南](docs/zh/configuration.md)
  - [架构设计](docs/zh/architecture.md)
  - [开发指南](docs/zh/development.md)
  - [API 参考](docs/zh/api.md)
  - [常见问题](docs/zh/faq.md)
  - [更新日志](docs/zh/changelog.md)

## License

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

## Acknowledgments

- [National Microbiology Data Center (NMDC)](https://nmdc.cn/) — for providing the data platform
- [Model Context Protocol](https://modelcontextprotocol.io/) — for the MCP specification
- Institute of Microbiology, Chinese Academy of Sciences