nmdc-mcp
OfficialProvides a client that uses OpenAI's API to query the NMDC database.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@nmdc-mcp show me metagenome samples from marine environments"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 syncRelated MCP server: splunk-mcp
Usage
You can use the CLI:
nmdc-mcpOr 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 devDevelopment 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 packageTesting
# 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 protocolMCP 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-mcpGoose Setup
goose session --with-extension "uvx nmdc-mcp"License
MIT
Available Tools
16 toolsfetch_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
Scored across 16 tools
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.
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.
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.).
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
Related MCP Connectors
Your prompt library in any MCP client: list, fetch, save and version prompt templates.
Prompt evals over MCP: run a prompt on your dataset, score each output 1-5 with an LLM judge.
Generate contextual prompts and reusable agent skills, evaluate prompts with the 16-dimension Prompt Score, and manage saved work in PromptDrive. Twelve MCP tools also provide authorized access to private Memory for source-grounded answers. Connect over Streamable HTTP using OAuth 2.1 and PKCE. Generation consumes account quota and automatically saves successful results; Memory access follows account permissions and plan limits.
Query SEC EDGAR filings, XBRL financials, and company data via MCP. STDIO or Streamable HTTP.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceFastMCP 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.3MIT
- AlicenseBqualityDmaintenanceA 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 resources12106Apache 2.0
- AlicenseNot gradedqualityDmaintenanceLightweight MCP server for providing user prompts defined in Markdown with argument support.6BSD 3-Clause
- AlicenseAqualityDmaintenanceEnables storage, versioning, and retrieval of prompts with rich metadata via MCP tools, supporting stdio and SSE transports.310 npm3ISC