setup

ENCODE Toolkit Setup

When to Use

• User needs help installing or configuring the ENCODE Toolkit MCP server
• User is getting connection errors or server startup failures
• User asks "how do I set up ENCODE?" or "install ENCODE toolkit"
• User needs to configure ENCODE credentials for restricted data access
• User wants to verify their ENCODE server connection is working
• User is setting up a new environment and needs the ENCODE plugin

Help the user set up the ENCODE Toolkit server. The server connects Claude to the ENCODE Project genomics database — the largest public catalog of functional genomic elements with 8,000+ experiments across 50+ assay types.

Installation

The ENCODE Toolkit server is installed via uvx (recommended) or pip:

For Claude Code (CLI)

claude mcp add encode -- uvx encode-toolkit

For Claude Desktop

Add to claude_desktop_config.json:

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

{
  "mcpServers": {
    "encode": {
      "command": "uvx",
      "args": ["encode-toolkit"]
    }
  }
}

Then restart Claude Desktop.

For VS Code (Claude Extension)

Add to your VS Code settings.json (Ctrl/Cmd + Shift + P → "Preferences: Open Settings (JSON)"):

{
  "claude.mcpServers": {
    "encode": {
      "command": "uvx",
      "args": ["encode-toolkit"]
    }
  }
}

For Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "encode": {
      "command": "uvx",
      "args": ["encode-toolkit"]
    }
  }
}

For Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "encode": {
      "command": "uvx",
      "args": ["encode-toolkit"]
    }
  }
}

Alternative: pip install

pip install encode-toolkit
encode-toolkit  # Run the server

Verify Installation

After setup, test the connection with these verification queries (run them in order):

Step 1: Check metadata access

Ask: "List available ENCODE assay types"

• This calls encode_get_metadata(metadata_type="assays")
• Expected: Returns 50+ assay types including ChIP-seq, ATAC-seq, RNA-seq, WGBS, Hi-C

Step 2: Test search

Ask: "Search for ATAC-seq experiments on human brain"

• This calls encode_search_experiments(assay_title="ATAC-seq", organ="brain", organism="Homo sapiens")
• Expected: Returns experiment accessions (ENCSR...) with assay, biosample, and status info

Step 3: Test facets

Ask: "What organs have the most ENCODE data?"

• This calls encode_get_facets(facet_field="organ")
• Expected: Returns organ counts showing brain, liver, heart, etc. ranked by experiment count

If all three work, your setup is complete.

Authentication

Most ENCODE data is public and needs no authentication. For restricted/unreleased data:

1. Get API credentials from https://www.encodeproject.org/profile/ (requires ENCODE account)
2. Store them:

`` Ask: "Store my ENCODE credentials" → Calls encode_manage_credentials(action="store", access_key="...", secret_key="...") ``

1. Credentials are encrypted via the OS keyring (macOS Keychain, Windows Credential Manager, or Linux Secret Service)
2. To verify: encode_manage_credentials(action="status")
3. To remove: encode_manage_credentials(action="remove")

20 Available Tools

After setup, these tools are available:

| Category | Tools | Purpose | |----------|-------|---------| | Search | encode_search_experiments, encode_get_facets, encode_get_metadata | Find experiments, explore data landscape, get valid filter values | | Experiment Details | encode_get_experiment, encode_compare_experiments | Get full experiment metadata, compare two experiments | | Files | encode_search_files, encode_list_files, encode_get_file_info | Find files, list files for an experiment, get file details | | Download | encode_download_files, encode_batch_download | Download individual or batch files with MD5 verification | | Tracking | encode_track_experiment, encode_list_tracked, encode_get_tracking_summary | Local experiment tracking with SQLite | | Provenance | encode_log_derived_file, encode_get_provenance | Log analysis outputs with full lineage | | Citations | encode_get_citations, encode_link_reference | Publication data, cross-reference to PubMed/GEO | | Credentials | encode_manage_credentials | Store/remove API credentials | | Collection | encode_summarize_collection | Summarize tracked experiment portfolio |

First-Run Walkthrough: Pancreatic Islet Epigenomics

This walkthrough demonstrates a complete workflow from installation to data exploration.

1. Explore what's available

"What ENCODE assay types are available for human pancreas?"
→ encode_get_facets(facet_field="assay_title", organ="pancreas", organism="Homo sapiens")

2. Find specific experiments

"Find all histone ChIP-seq experiments on human pancreas"
→ encode_search_experiments(assay_title="Histone ChIP-seq", organ="pancreas", organism="Homo sapiens")

3. Examine an experiment

"Get details for ENCSR123ABC"
→ encode_get_experiment(accession="ENCSR123ABC")

4. Find the right files

"List the preferred BED files for ENCSR123ABC"
→ encode_list_files(accession="ENCSR123ABC", file_format="bed", assembly="GRCh38")

5. Download data

"Download the IDR-thresholded peaks for ENCSR123ABC"
→ encode_download_files(accession="ENCSR123ABC", file_format="bed", output_type="IDR thresholded peaks")

6. Track your experiment

"Track ENCSR123ABC in my local database with note 'H3K27ac pancreatic islets'"
→ encode_track_experiment(accession="ENCSR123ABC", notes="H3K27ac pancreatic islets")

Cross-Database Integration

The ENCODE Toolkit works alongside other MCP servers and REST APIs:

| Database | Access Method | What It Adds | |----------|--------------|--------------| | PubMed | MCP server (search_articles) | Literature citations for ENCODE experiments | | bioRxiv | MCP server (search_preprints) | Preprint discovery for latest research | | ClinicalTrials.gov | MCP server (search_trials) | Clinical trial cross-reference | | Open Targets | MCP server (query_open_targets_graphql) | Drug target identification | | GTEx | REST API via skill | Tissue-specific expression context | | ClinVar | REST API via skill | Clinical variant annotation | | GWAS Catalog | REST API via skill | Trait-associated variant lookups | | gnomAD | GraphQL via skill | Population allele frequencies | | Ensembl | REST API via skill | VEP annotation, Regulatory Build | | UCSC | REST API via skill | Genome browser tracks, cCRE data | | GEO | E-utilities via skill | Complementary expression datasets | | JASPAR | REST API via skill | TF binding motif databases | | CellxGene | REST API via skill | Single-cell expression atlases |

47 Expert Skills

Beyond the 20 tools, the ENCODE Toolkit includes 47 skills providing domain expertise:

• Core (5): setup, search-encode, download-encode, track-experiments, cross-reference
• Analysis (9): quality-assessment, integrative-analysis, regulatory-elements, epigenome-profiling, compare-biosamples, visualization-workflow, motif-analysis, peak-annotation, batch-analysis
• Pipelines (7): pipeline-chipseq, pipeline-atacseq, pipeline-rnaseq, pipeline-wgbs, pipeline-hic, pipeline-dnaseseq, pipeline-cutandrun
• External DBs (9): gtex-expression, clinvar-annotation, cellxgene-context, gwas-catalog, jaspar-motifs, ensembl-annotation, geo-connector, gnomad-variants, ucsc-browser
• Workflows (10): data-provenance, cite-encode, variant-annotation, pipeline-guide, single-cell-encode, disease-research, publication-trust, bioinformatics-installer, scientific-writing, liftover-coordinates
• **Data Aggregation (4)