/setup

name: setup
description: Set up the ENCODE Toolkit server connection. Use when the user needs help installing, configuring, or troubleshooting the ENCODE connector.
disable-model-invocation: true

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()`
• 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="...")

3. Credentials are encrypted via the OS keyring (macOS Keychain, Windows Credential Manager, or Linux Secret Service) 4. To verify: `encode_manage_credentials(action="check")` 5. To remove: `encode_manage_credentials(action="clear")`

---

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(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(experiment_accession="ENCSR123ABC", file_format="bed", assembly="GRCh38")

5. Download data

"Download the IDR-thresholded peaks for ENCSR123ABC"
→ encode_list_files(experiment_accession="ENCSR123ABC", file_format="bed", output_type="IDR thresholded peaks")
→ encode_download_files(file_accessions=["ENCFF..."], download_dir="/data/encode")

6. Track your experiment

"Track ENCSR123ABC in my local database with note 'H3K27ac