ncbi-sequence-fetch

NCBI Sequence Fetch

Prerequisites

1. uv: Read the uv skill and follow its Setup instructions to ensure uv is installed and on PATH.
2. User Notification: If .licenses/ncbi_sequence_fetch_LICENSE.txt does not already exist in the workspace root directory then (1) prominently notify the user to check the terms at https://www.ncbi.nlm.nih.gov/ and https://www.ncbi.nlm.nih.gov/home/about/policies/, then (2) create the file recording the notification text and timestamp.
3. .env file: Make sure the .env file exists in your home directory. Create one if it does not exist.
4. NCBI_API_KEY (optional): Raises the NCBI rate limit from 3 to 10 requests/second. The skill works without it, but a key is recommended if the user plans many queries or encounters a 429 error. You can register for a key for free at https://www.ncbi.nlm.nih.gov/account/settings/. You MUST use the safe credentials protocol in the credentials skill to check for and request this key if this skill looks relevant to the user's request.

Core Rules

• Use the Wrapper: ALWAYS execute the provided helper scripts to query the database rather than accessing the database directly. The scripts automatically enforce the required rate limit gracefully.
• API Key Support: If the user provides an NCBI_API_KEY in their environment, the query speed limits are automatically increased significantly.
• Notification: If this skill is used, ensure this is mentioned in the output.

Overview

Wraps NCBI's Entrez E-utilities (efetch, esearch, elink, esummary) for retrieving protein and nucleotide sequences. Provides 10 subcommands covering the full range of sequence retrieval workflows:

• fetch-protein — Direct protein accession lookup (GenPept, RefSeq)
• fetch-nucleotide — Direct nucleotide accession lookup
• cds-translate — Fetch CDS and translate to protein (3 methods)
• search — Free-text search of any NCBI database
• elink — Follow cross-database links (PubMed→Protein, etc.)
• gene-protein — Search protein by gene name + organism
• locus-protein — Search protein by locus tag + organism
• pubmed-proteins — Find proteins linked to a PubMed article
• patent-search — Extract protein sequences from patents
• organism-length — Last-resort search by organism + exact AA length

Utility Scripts

scripts/ncbi_fetch.py — Single script with subcommands.

All subcommands write structured JSON output. Use --output FILE to save to a file, or omit it to print to stdout. A human-readable summary is always printed to stdout.

1. Fetch Protein by Accession

Fetches protein FASTA from NCBI by accession (XP_, NP_, GenPept, etc.)

uv run scripts/ncbi_fetch.py fetch-protein XP_022033624 -o /tmp/result.json
uv run scripts/ncbi_fetch.py fetch-protein NP_001234567 ABC12345.1

2. Fetch Nucleotide by Accession

Fetches nucleotide FASTA from NCBI by accession.

3. CDS Translate

Fetches a CDS/nucleotide accession and translates to protein sequence. Tries three approaches in order: 1. NCBI's pre-translated CDS protein (fasta_cds_aa)

2. GenBank XML CDS annotation translations 3. Raw nucleotide → 6-frame ORF finding

If the accession is a genomic record (not mRNA/CDS), the tool will report is_genomic: true so you can fall back to a homology-based approach instead.

4. Search Any Database

Free-text search using Entrez query syntax. Supports all NCBI databases.

5. Cross-Database Links (elink)

Follow NCBI's cross-database links (e.g., PubMed article → linked proteins).

6. Gene + Organism Search

Searches for protein sequences by gene name and organism. Searches NCBI Protein with [Gene Name] and [Organism] qualifiers.

7. Locus Tag Search

Searches by locus tag in both NCBI Protein and Nuccore databases. Extracts CDS translations from GenBank XML when direct protein hits aren't available.

8. PubMed-Linked Proteins

Finds protein sequences linked to a PubMed article. Searches NCBI Protein by PMID, follows elink PubMed→Protein, and extracts CDS translations from linked Nuccore records.

9. Patent Sequence Search

Two modes:

By patent number — fetches all protein sequences from a specific patent: bash uv run scripts/ncbi_fetch.py patent-search --patent-number US10123456 -o /tmp/patent.json

By keywords — searches NCBI Protein with patent[Properties] filter: bash uv run scripts/ncbi_fetch.py patent-search --keywords WRR4B Albugo --organism "Arabidopsis thaliana" -o /tmp/patent.json

[!IMPORTANT] Patent convention: In molecular biology patents, SEQ ID NO: 1 is typically the DNA sequence and SEQ ID NO: 2 is the primary protein. Higher SEQ ID NOs are variants or related sequences. Prefer Sequence 2 when selecting the primary protein of interest.

10. Organism + Length Search

Last-resort search when only organism and expected protein length are known. Uses NCBI's [SLEN] filter for exact length matching.

[!NOTE] This often returns multiple candidates. Use the JSON output headers to identify the correct protein.

Workflow

Standard Sequence Retrieval Cascade

When trying to find a protein sequence, follow this priority order:

1. Direct accession — fetch-protein with GenPept/RefSeq accession
2. CDS translation — cds-translate with nucleotide/CDS accession
3. PubMed-linked — pubmed-proteins with PMID + gene name
4. Locus lookup — locus-protein with locus tag + organism
5. Gene + organism — gene-protein with gene name + organism
6. Patent search — patent-search with patent number or keywords
7. Organism + length — organism-length as last resort

Interpreting Results

• All subcommands return JSON with a results array
• Each result has sequence (AA string), length, and header/metadata
• When multiple results are returned, select by:
  • Closest match to expected length (target_length)
  • Header relevance (matching gene name, "disease resistance" keywords)
  • Source priority (RefSeq > GenPept > patent)

Reference

• NCBI E-utilities docs: https://www.ncbi.nlm.nih.gov/books/NBK25499/
• Entrez search syntax: https://www.ncbi.nlm.nih.gov/books/NBK49540/
• Database list: protein, nuccore, gene, pubmed, pmc, biosample, etc.
• Common accession formats:
  • XP_ / NP_ — NCBI RefSeq protein
  • AAA to AZZ + digits — GenPept (translated GenBank)
  • MK, MN, HQ, etc. + digits — GenBank nucleotide
  • ENSG, ENST, ENSP — Ensembl (use ensembl-database skill instead)
  • Q, P, O + digits — UniProt (use uniprot-database skill instead)