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:

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:

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): histone-aggregation, accessibility-aggregation, hic-aggregation, methylation-aggregation
• Meta-Analysis (2): scrna-meta-analysis, multi-omics-integration
• Functional Genomics (1): functional-screen-analysis

Pitfalls & Troubleshooting

Code Examples

1. Verify server connection with metadata query

encode_get_metadata(metadata_type="assays")

Expected output:

{
  "assays": ["ATAC-seq", "ChIP-seq", "CUT&RUN", "CUT&Tag", "DNase-seq", "Hi-C", "MPRA", "RNA-seq", "STARR-seq", "WGBS", "eCLIP", "scATAC-seq", "scRNA-seq"]
}

2. Test search functionality

encode_search_experiments(assay_title="ATAC-seq", organ="brain", organism="Homo sapiens", limit=3)

Expected output:

{
  "total": 32,
  "results": [
    {"accession": "ENCSR000AAA", "assay_title": "ATAC-seq", "biosample_summary": "brain", "status": "released"}
  ]
}

3. Test facet exploration

encode_get_facets(facet_field="organ", organism="Homo sapiens")

Expected output:

{
  "facets": {
    "organ": {"brain": 450, "blood": 380, "liver": 220, "heart": 180, "lung": 150}
  }
}

Related Skills

Presenting Results

When reporting setup results:

• Connection status: Confirm the ENCODE Toolkit server is connected and responding. Report the server version if available
• Available tools: List the 20 available ENCODE tools grouped by function (search, download, track, cross-reference, credentials)
• Test query result: Run a simple validation query (e.g., encode_get_metadata(metadata_type="assays")) and confirm it returns results successfully
• Authentication status: Note whether credentials are configured (for restricted data) or that public data access requires no authentication
• Troubleshooting: If any issues were encountered during setup, summarize the problem and resolution
• Next steps: Suggest search-encode to find experiments, or encode_get_facets to explore what ENCODE data is available for their research area

For the request: "$ARGUMENTS"