# BacDive MCP Server

<p align="center">
  <strong>An MCP (Model Context Protocol) server for the BacDive bacterial biodiversity database</strong>
</p>

<p align="center">
  <em>⚠️ This is an unofficial, community-driven project. It is not affiliated with, endorsed by, or officially connected to DSMZ (German Collection of Microorganisms and Cell Cultures) or the BacDive database team.</em>
</p>

<p align="center">
  <a href="#overview">Overview</a> ·
  <a href="#features">Features</a> ·
  <a href="#installation">Installation</a> ·
  <a href="#configuration--usage">Configuration & Usage</a> ·
  <a href="#available-tools">Available Tools</a> ·
  <a href="#development">Development</a> ·
  <a href="#license">License</a> ·
  <a href="./README_CN.md">中文</a>
</p>

---

## Overview

[BacDive](https://bacdive.dsmz.de/) (Bacterial Diversity Metadatabase) is an online database developed and maintained by the German Collection of Microorganisms and Cell Cultures (DSMZ). The >80,000 bacterial and archaeal strains are catalogued in BacDive with detailed information covering physiology, morphology, taxonomy, culture conditions, metabolism, enzymology activities, antibiotic resistance, sequences, and many more.

This project is an MCP (Model Context Protocol) server that enables AI large language models (such as Claude) to directly query and retrieve data from the BacDive database. Through this MCP server, the AI assistants can:

- 🔍 Search for strains by species or genus name
- 📋 Retrieve full strain details by BacDive ID
- 🧫 Search for culture media by name or ID
- 🧬 Search for 16S rRNA or genome sequences
- 📖 Perform free-text searches across the entire taxon database

## Features

### Data Query Capabilities

| Feature | Description |
|---------|-------------|
| **Strain Search** | Search strains by species name (e.g., *Escherichia coli*) or genus name |
| **Full-text Search** | Search taxa by any keyword (e.g., "thermophilic", "spore-forming", "nitrogen-fixing") |
| **Strain Details** | Retrieve full strain information by BacDive ID (taxonomy, morphology, culture conditions, metabolism, enzymology, resistance, safety, etc.) |
| **DSM Number Search** | Search by DSMZ strain number (e.g., DSM 3) |
| **Culture Medium Search** | Search culture media by name or retrieve full composition by ID |
| **16S rRNA Search** | Search 16S rRNA gene sequences by species/genus |
| **Genome Search** | Search genome sequences by species/genus |
| **Browse All** | Paginated browsing of all taxa in BacDive |
| **Health Check** | Check BacDive API connectivity |

### Technical Features

- TypeScript implementation with type safety
- Uses Node.js native `https` module —zero external HTTP dependencies
- Communicates with MCP clients via standard size transport
- Compatible with any MCP client (Claude Desktop, Cursor, etc.)

## Installation

### Prerequisites

- **Node.js** >= 18.0.0
- **npm** or **yarn** or **pnpm** (any one)

### Build from Source

```bash
# Clone or download this project locally
cd BacDive-MCP

# Install dependencies
npm install

# Compile TypeScript
npm run build
```

After compilation, the runnable file will be at `dist/index.js`.

### Global Install (Optional)

```bash
npm run build
npm link

# Now you can run it globally
bacdive-mcp
```

## Configuration & Usage

### Claude Desktop Configuration

Add the BacDive MCP server to your Claude Desktop configuration file:

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

```json
{
  "mcpServers": {
    "bacdive-mcp": {
      "command": "node",
      "args": [
        "C:/your/path/to/BacDive-MCP/dist/index.js"
      ]
    }
  }
}
```

> **Tip**: Replace `C:/your/path/to/BacDive-MCP/dist/index.js` with your actual project path.

### Cursor Configuration

Add to Cursor's MCP settings:

```json
{
  "mcpServers": {
    "bacdive-mcp": {
      "command": "node",
      "args": [
        "C:/your/path/to/BacDive-MCP/dist/index.js"
      ]
    }
  }
}
```

### Generic MCP Client Configuration

Any MCP-compatible client can connect to this server via stdeo. The server startup command is:

```bash
node dist/index.js
```

### Manual Testing

```bash
# Build
npm run build

# Start the server (communicates via stdin/stdout)
npm start
```

## Available Tools

This MCP server provides the following 10 tools:

### 1. `bacdive_search_strain` — Strain Search

Search for strains by species and/or genus name.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `species` | string | one of two | Full or partial species name (e.g., `"Escherichia coli"`) |
| `genus` | string | one of two | Full or partial genus name (e.g., `"Bacillus"`) |
| `page` | number | no | Page number, default 1 |

**Example call:**
```json
{
  "species": "Escherichia coli",
  "page": 1
}
```

### 2. `bacdive_search_taxon` — Full-text Search

Search across the entire taxon database with free text.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | yes | Search query (e.g., `"thermophilic"`, `"spore-forming"`) |
| `page` | number | no | Page number, default 1 |

### 3. `bacdive_get_strain_by_id` — Get Strain Details

Retrieve full strain information by BacDive ID.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `id` | number | yes | BacDive strain ID (e.g., `2`) |

**Returned content includes:**

- General information (DSMZ strain number, accession, dates, etc.)
- Name & taxonomic classification (species, genus, family, order, class, phylum, domain, full name, LPSN, synonyms, etc.)
- Morphology
- Culture and growth conditions
- Physiology and metabolism
- Enzyme activities
- Antibiotic resistance
- Safety information
- Applications
- References
- Sequence information (16S rRNA gene, genome)
- External links

### 4. `bacdive_search_by_dsm_number` — Search by DSM Number

Search for a strain by its DSMZ strain number.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `dsm_number` | string | yes | DSMZ strain number (e.g., `"DSM 3"` or `"3"`) |

### 5. `bacdive_browse_taxa` — Browse All Taxa

Browse all taxa in the BacDive database with pagination.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `page` | number | no | Page number, default 1 |

### 6. `bacdive_search_culture_medium` — Search Culture Media

Search for culture media by name.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `medium_name` | string | yes | Full or partial medium name (e.g., `"Nutrient"`, `"LB"`) |
| `page` | number | no | Page number, default 1 |

### 7. `bacdive_get_culture_medium_by_id` — Get Culture Medium Details

Retrieve full culture medium information by DSMZ medium ID.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `medium_id` | number | yes | DSMZ medium ID (e.g., `1`) |

### 8. `bacdive_search_16s` — Search 16S rRNA Sequences

Search for 16S rRNA gene sequences by species or genus name.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `species` | string | one of two | Species name |
| `genus` | string | one of two | Genus name |
| `page` | number | no | Page number, default 1 |

### 9. `bacdive_search_genome` — Search Genomes

Search for genome sequences by species or genus name.

**Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `species` | string | one of two | Species name |
| `genus` | string | one of two | Genus name |
| `page` | number | no | Page number, default 1 |

### 10. `bacdive_ping` — Health Check

Check BacDive API connectivity.

**Parameters:** None

## Usage Examples

Here are some natural language conversation examples when using Claude Desktop:

### Example 1: Find a Specific Strain

> **User**: Help me search for E. coli (Escherichia coli) in the BacDive database.
>
> **AI Assistant**: (Calls the `bacdive_search_strain` tool and returns matching results)

### Example 2: Get Detailed Information

> **User**: For the strain with BacDive ID 2, give me its complete culture conditions and metabolism info.
>
> **AI Assistant**: (Calls `bacdive_get_strain_by_id` and extracts culture conditions and metabolism data)

### Example 3: Search for Culture Methods

> **User**: I need to culture a Bacillus subtilis strain. Help me find the Nutrient medium recipe.
>
> **AI Assistant**: (Calls `bacdive_search_culture_medium` and returns the medium recipe)

### Example 4: Trait-based Search

> **User**: Find thermophilic bacteria in BacDive.
>
> **AI Assistant**: (Calls `bacdive_search_taxon` with query "thermophilic")

## Project Structure

```
BacDive-MCP/
├── src/
│   ├── index.ts               # Entry point, starts MCP server
│   ├── server.ts              # MCP server core, tool definitions and handlers
│   └── bacdive-client.ts      # BacDive API client
├── examples/
│   └── claude_desktop_config.json  # Claude Desktop config example
├── package.json               # Project configuration and dependencies
├── tsconfig.json              # TypeScript compilation config
├── .env.example               # Environment variables example
├── .gitignore
├── README.md                  # English documentation (this file)
├── README_CN.md               # Chinese documentation
└── LICENSE                    # MIT License
```

## Development

### Development Setup

```bash
# Install dependencies
npm install

# Watch mode compilation (optional)
# Use tsc --watch

# Build
npm run build

# Run
npm start

# Type check (no output files)
npm run lint
```

### Adding New Tools

1. Add a new tool definition in the `TOOLS` array in `src/server.ts`
2. Add a corresponding `case` branch in the `handleToolCall` function
3. Add the corresponding API client method in `src/bacdive-client.ts` (if needed)
4. Rebuild and run

### Code Architecture

- **`bacdive-client.ts`**: Wraps BacDive REST API HTTP calls with type-safe methods. Uses Node.js built-in `https` module — no external dependencies needed.
- **`server.ts`**: Defines MCP tool metadata (name, description, input schema) and handlers. Routes tool calls to the appropriate BacDiveClient methods.
- **`index.ts`**: Entry point — creates the client, server, and stdio transport, then starts the service.

## API Reference

BacDive REST API documentation:

- Homepage: https://bacdive.dsmz.de/
- API base path: `https://api.bacdive.dsmz.de/api/v1/`
- Main endpoints:
  - `GET /taxon/` — Taxon search
  - `GET /strain/{id}/` — Strain details
  - `GET /culturemedium/` — Culture medium search
  - `GET /culturemedium/{id}/` — Culture medium details
  - `GET /sequence_16s/` — 16S rRNA search
  - `GET /genome/` — Genome search

## About BacDive

BacDive (https://bacdive.dsmz.de/) is a bacterial diversity metadatabase maintained by DSMZ, containing detailed descriptions of over 80,000 strains covering taxonomy, morphology, physiology, ecology, molecular biology, and more. The database is publicly accessible and is an important resource for microbiological research.

> **Disclaimer**: This project is an independent, unofficial MCP server wrapper for the BacDive API. All BacDive data and the BacDive API are owned and operated by DSMZ. For official information, please visit [https://bacdive.dsmz.de/](https://bacdive.dsmz.de/).

---

## License

[MIT License](./LICENSE)