Skip to main content
Glama
nmdc-mcp

nmdc-mcp

Official

NMDC MCP

A fastmcp-based tool for writing prompts against data in the NMDC database.

Installation

You can install the package from source using uv:

uv sync

Related MCP server: splunk-mcp

Usage

You can use the CLI:

nmdc-mcp

Or import in your Python code: # TODO incorrect instructions

from nmdc_mcp.main import create_mcp

mcp = create_mcp()
mcp.run()

Or utilize the nmdc_mcp.client. This client uses OpenAI API and assumes you have API_KEY set in a .env file in the root directory of this repo. The BASE_URL and MODEL are also customizable in .env. For PNNL staff that want to run via this client - the BASE_URL and MODEL are specific. Contact Olivia Hess if you need help setting these values up.

uv run 'path/to/nmdc_mcp/client.py' 'path/to/nmdc_mcp/main.py'

Or using python

python 'path/to/nmdc_mcp/client.py' 'path/to/nmdc_mcp/main.py'

Development

Local Setup

# Clone the repository
git clone https://github.com/microbiomedata/nmdc-mcp.git
cd nmdc-mcp

# Install development dependencies
make dev

Development Workflow

The project uses a comprehensive Makefile for development tasks:

# Run all development checks (tests, formatting, linting, type checking)
make all

# Individual commands
make dev           # Install development dependencies
make test-coverage # Run tests with coverage
make format        # Format code with black
make lint          # Lint with ruff
make mypy          # Type checking
make deptry        # Check for unused dependencies
make build         # Build package

Testing

# Run all tests with coverage
make test-coverage

# Run specific test types
make test-unit         # Unit tests only
make test-integration  # Integration tests
make test-real-api     # Tests against real NMDC API
make test-mcp          # Test MCP protocol

MCP Integration

Claude Desktop Setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "nmdc-mcp": {
      "command": "uvx",
      "args": ["nmdc-mcp"]
    }
  }
}

Claude Code MCP Setup

claude mcp add -s project nmdc-mcp uvx nmdc-mcp

Goose Setup

goose session --with-extension "uvx nmdc-mcp"

License

MIT

Available Tools

16 tools
fetch_and_filter_gff_by_pfam_domainsA

Use this tool to analyze GFF files for PFAM domains and show genomic locations. Use AFTER get_samples_by_annotation to get the actual gene coordinates and genomic context. Takes a data_object_id from the previous search results and downloads the entire GFF file by default to show specific gene annotations containing the PFAM domains. Only use sample_bytes parameter if you specifically need to limit download size.

Inputs: data_object_id (required), pfam_domain_ids (required), max_rows, sample_bytes.

get_all_collection_idsB

Use this tool to get lists of IDs from NMDC collections in batches. Useful for sampling or systematic analysis of large datasets.

Inputs: collection, batch_size, max_batches.

get_biosamples_for_studyC

Use this tool to find all biosamples associated with a specific study. Returns a list of biosample IDs and metadata.

Inputs: study_id (required), max_records.

get_collection_namesA

Use this tool to discover what types of data are available in the NMDC database. Returns a list of collection names like 'biosample_set', 'study_set', etc.

Inputs: no named parameters.

get_collection_statsA

Use this tool to get statistics about NMDC collections including document counts. Helps understand the size and scope of available data.

Inputs: no named parameters.

get_data_objects_by_pfam_domainsC

Use this tool to find biosamples that contain specific PFAM protein domains. Returns structured data about biosamples, their activities, and data objects. Perfect for finding samples with particular functional capabilities.

Inputs: pfam_domain_ids (required), biosample_limit.

get_entities_by_ids_with_projectionA

Use this tool to retrieve specific fields from multiple NMDC entities by their IDs. Efficient for batch operations with field filtering.

Inputs: entity_ids (required), collection (required), projection, max_page_size.

get_entity_by_idC

Use this tool to retrieve any NMDC entity by its ID. Works with biosamples, studies, data objects, and other NMDC entities.

Inputs: entity_id (required).

get_entity_by_id_with_projectionA

Use this tool to retrieve specific fields from an NMDC entity by ID. More efficient than getting full entities when you only need certain fields.

Inputs: entity_id (required), collection (required), projection.

get_samples_by_annotationA

Use this tool to find biosamples with specific functional annotations. Returns COMPLETE biosample records including all data objects (GFF files, protein files, etc.) with their IDs and URLs. ALWAYS set max_records to match the user's request (e.g., if they ask for '1 sample' or 'a sample', set max_records=1). Use max_records, NOT limit, to control how many samples to return. Required formats: PFAM domains use 'PFAM:PF04183', KEGG use 'KEGG.ORTHOLOGY:K00001', COG use 'COG:COG0001', GO use 'GO:GO0000001'. When users want genomic locations of domains, use this first to find samples, then use fetch_and_filter_gff_by_pfam_domains with a GFF data_object_id from the results.

Inputs: gene_function_ids (required), max_records, limit, offset.

get_samples_by_ecosystemC

Use this tool to find biosamples from specific ecosystem types, categories, or subtypes. Perfect for studying particular environments like soil, marine, or host-associated microbiomes.

Inputs: ecosystem_category, ecosystem_type, ecosystem_subtype, max_records.

get_samples_in_elevation_rangeB

Use this tool to find biosamples collected within a specific elevation range. Perfect for studying altitude-related microbial communities.

Inputs: min_elevation (required), max_elevation (required).

get_samples_within_lat_lon_bounding_boxC

Use this tool to find biosamples collected within a specific geographic bounding box defined by latitude and longitude coordinates.

Inputs: lower_lat (required), upper_lat (required), lower_lon (required), upper_lon (required).

get_study_doi_detailsB

Use this tool to get detailed DOI information for a study, including publication DOIs, dataset DOIs, and award DOIs.

Inputs: study_id (required).

get_study_for_biosampleC

Use this tool to find the study associated with a specific biosample. Returns study information and metadata.

Inputs: biosample_id (required).

search_studies_by_doi_criteriaC

Use this tool to search for studies based on DOI criteria like provider, category, or DOI value patterns. Perfect for finding published studies or datasets from specific sources.

Inputs: doi_provider, doi_category, doi_value_contains, max_results.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 16 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: fetching GFF by PFAM domains, retrieving collection IDs, biosamples by study, collection names/stats, data objects by PFAM, entities by ID with/without projection, samples by annotation/ecosystem/elevation/lat-lon, study DOI details, study for biosample, and searching studies by DOI. Even similar functions like entity retrieval are differentiated by batch vs single and projection vs full.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern using snake_case, primarily starting with 'get_' or 'fetch_', with clear and descriptive nouns. The only variation is 'search_studies_by_doi_criteria', but it still maintains the pattern. No mixing of camelCase or inconsistent verb styles.

    Tool Count4/5

    16 tools is slightly above the typical 3-15 range, but it is well-scoped for the NMDC database query domain. Each tool serves a specific purpose without redundancy, and the count is reasonable given the variety of query needs (by ID, by annotation, by location, etc.).

    Completeness4/5

    The tool set covers a comprehensive range of query operations for the NMDC database: listing collections, retrieving entities by ID, searching biosamples by multiple criteria (study, ecosystem, elevation, location, PFAM domains), and accessing study DOIs. Minor gaps include lack of direct query for data objects by other attributes, but for a read-only query interface, this is nearly complete.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      FastMCP is a comprehensive MCP server allowing secure and standardized data and functionality exposure to LLM applications, offering resources, tools, and prompt management for efficient LLM interactions.
      3
      MIT
    • A
      license
      B
      quality
      D
      maintenance
      A FastMCP-based tool for interacting with Splunk Enterprise/Cloud through natural language. This tool provides a set of capabilities for searching Splunk data, managing KV stores, and accessing Splunk resources
      12
      106
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Lightweight MCP server for providing user prompts defined in Markdown with argument support.
      6
      BSD 3-Clause