{"id":42117672,"url":"https://github.com/aidenlab/juicebox-mcp","last_synced_at":"2026-01-26T14:11:38.875Z","repository":{"id":328043508,"uuid":"1113332253","full_name":"aidenlab/juicebox-mcp","owner":"aidenlab","description":"MCP-enabled version of juicebox.js - HiC contact matrix visualization","archived":false,"fork":false,"pushed_at":"2025-12-18T15:51:17.000Z","size":36135,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-18T18:17:37.210Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aidenlab.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-09T20:43:57.000Z","updated_at":"2025-12-18T15:51:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/aidenlab/juicebox-mcp","commit_stats":null,"previous_names":["aidenlab/juicebox-mcp"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/aidenlab/juicebox-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidenlab%2Fjuicebox-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidenlab%2Fjuicebox-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidenlab%2Fjuicebox-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidenlab%2Fjuicebox-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aidenlab","download_url":"https://codeload.github.com/aidenlab/juicebox-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aidenlab%2Fjuicebox-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28780339,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T13:55:28.044Z","status":"ssl_error","status_checked_at":"2026-01-26T13:55:26.068Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-26T14:11:38.751Z","updated_at":"2026-01-26T14:11:38.854Z","avatar_url":"https://github.com/aidenlab.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Juicebox MCP Server\n\nAn MCP (Model Context Protocol) server that enables Claude to control Juicebox Hi-C contact map visualizations through natural language. Search for Hi-C datasets, load maps, navigate genomic loci, configure visualizations, and explore chromatin architecture—all through conversation with Claude.\n\n## What is This?\n\nJuicebox MCP Server is derived from the JavaScript version of Juicebox and transforms it into an **AI-powered research assistant** for exploring Hi-C contact maps. Instead of manually navigating web interfaces and configuring visualizations, you can:\n\n- **Search** for Hi-C datasets using natural language (\"Show me human K562 cell maps\")\n- **Load** maps and tracks with intelligent recommendations\n- **Navigate** to genomic regions by gene name or coordinates\n- **Configure** visualizations through conversation\n- **Discover** complementary datasets automatically\n- **Share** visualizations via shareable URLs\n\nThe server connects Claude Desktop to a browser-based Juicebox frontend, enabling seamless control of Hi-C visualizations through natural language.\n\n## Installation\n\n### Prerequisites\n\n- **Claude Desktop** installed ([Download here](https://claude.ai/download))\n\n### Install the MCP Server\n\n1. **Download the MCP Server Package**\n   - Download the `.mcpb` file directly: [juicebox-mcp-20251219-164324.mcpb](https://github.com/aidenlab/juicebox-mcp/blob/main/juicebox-mcp-20251219-164324.mcpb)\n   - Or build it yourself (see [Building from Source](#building-from-source) below)\n\n2. **Install in Claude Desktop**\n   - Open Claude Desktop\n   - Go to **Settings** (macOS: `Cmd + ,` | Windows: `Ctrl + ,`)\n   - Navigate to **Developer** → **Add MCP Server**\n   - Click **Install from file**\n   - Select the `.mcpb` file you downloaded\n   - Claude Desktop will automatically extract and configure the server\n\n3. **Verify Installation**\n   - The server should appear in your MCP servers list\n   - Restart Claude Desktop if needed\n\nThat's it! The MCP server is now installed and ready to use.\n\n## Getting Started\n\n### Step 1: Open the Browser Frontend\n\nIn Claude Desktop, ask Claude to open Juicebox:\n\n```\nYou: \"Open Juicebox\" or \"Get the Juicebox URL\"\n```\n\nClaude will provide a URL—open it in your web browser. The browser will automatically connect to the MCP server running in Claude Desktop.\n\n### Step 2: Start Exploring\n\nOnce the browser is open, you can start exploring Hi-C data through natural language:\n\n```\nYou: \"Find Hi-C maps for human K562 cells\"\n\nClaude: [Searches available data sources]\n        \"I found 8 K562 cell line maps. Here are the top results:\n        - Map #1: ENCODE K562 Hi-C (hg38, high resolution)\n        - Map #2: 4DN K562 Hi-C (hg38, recent data)\n        ...\n        Which would you like to load?\"\n\nYou: \"Load the first one\"\n\nClaude: [Loads the map and displays it in your browser]\n```\n\n## Usage Examples\n\n### Search and Load Hi-C Maps\n\n```\nYou: \"Find Hi-C maps for human K562 cells\"\n\nClaude: [Searches available data sources]\n        \"I found 8 K562 cell line maps. Here are the top results...\"\n\nYou: \"Load the first one\"\n\nClaude: [Loads the map and displays it in your browser]\n```\n\n### Navigate to Genomic Regions\n\n```\nYou: \"Go to the BRCA1 gene\"\n\nClaude: [Looks up BRCA1 coordinates]\n        [Navigates to chr17:43,044,295-43,125,482]\n        \"I've navigated to the BRCA1 gene region. Would you like to \n        zoom in or add any annotation tracks?\"\n```\n\n### Load Complementary Data\n\n```\nYou: \"Add CTCF binding sites for this cell type\"\n\nClaude: [Discovers available CTCF tracks for the loaded biosample]\n        \"I found CTCF ChIP-seq data for K562 cells. Would you like \n        the fold change track or the peak calls?\"\n        \nYou: \"Both\"\n\nClaude: [Loads both tracks]\n        \"I've added CTCF fold change and peak tracks. The peaks are \n        shown as 2D annotations on the contact map.\"\n```\n\n### Configure Visualization\n\n```\nYou: \"Change the color scale to blue\"\n\nClaude: [Updates the foreground color]\n        \"I've changed the color scale to blue. The contact map now \n        uses a blue gradient to show interaction strength.\"\n```\n\n### Create Shareable Links\n\n```\nYou: \"Create a shareable link for this visualization\"\n\nClaude: [Generates a compressed session URL]\n        \"Here's a shareable link: https://t.3dg.io/abc123\n        Anyone can open this link to see your current visualization \n        with all maps, tracks, and settings.\"\n```\n\n## What You Can Do\n\n### 🧠 AI-Enhanced Capabilities\n\nClaude brings intelligent assistance to Hi-C exploration:\n\n- **Semantic Search**: Understands biological concepts (\"heart tissue\" finds related samples)\n- **Context-Aware Discovery**: Suggests complementary datasets based on what you've loaded\n- **Domain Knowledge**: Recommends appropriate normalizations, resolutions, and annotations\n- **Workflow Orchestration**: Handles multi-step processes automatically\n- **Intent Inference**: Makes sensible defaults while allowing full customization\n\n### 🔍 Data Source Integration\n\nSearch across multiple Hi-C data sources:\n\n- **4DN (4D Nucleome)**: Specialized 4D nucleome projects\n- **ENCODE**: Broad cell type coverage with standardized data\n\nClaude understands metadata relationships and can help you find the right datasets for your research.\n\n### 🎨 Full Visualization Control\n\nControl every aspect of the visualization:\n\n- Load main maps and control maps for comparison\n- Navigate by gene name, coordinates, or natural language\n- Zoom in/out and pan across the genome\n- Configure color scales and normalization methods\n- Add 1D tracks (bigWig, bedGraph) and 2D annotations (loops, domains)\n- Save and restore sessions\n- Create shareable URLs\n\n## Troubleshooting\n\n### Browser Won't Connect\n\n- Make sure Claude Desktop is running\n- Verify the MCP server is installed and enabled in Claude Desktop settings\n- Try asking Claude: \"Get the Juicebox URL\" to get a fresh connection URL\n- Check that your browser allows WebSocket connections to `localhost`\n\n### Maps Won't Load\n\n- Verify you have an active internet connection (maps are loaded from remote URLs)\n- Check that the URL is accessible (try opening it directly in your browser)\n- Ask Claude: \"Get server status\" to check the connection\n\n### Claude Doesn't Recognize Commands\n\n- Make sure the MCP server is enabled in Claude Desktop settings\n- Restart Claude Desktop after installing the server\n- Check that the server appears in your MCP servers list\n\n## Building from Source\n\nIf you want to build the MCP server yourself or contribute to development, see the [MCPB Build Guide](docs/mcp-notes/MCPB_BUILD_GUIDE.md) for detailed instructions.\n\nQuick build steps:\n\n```bash\ngit clone https://github.com/aidenlab/juicebox-mcp.git\ncd juicebox-mcp\nnpm install\nnpm run build:mcpb\n```\n\nThis creates a `.mcpb` package in the project root that can be installed in Claude Desktop.\n\n## Documentation\n\nFor more detailed information:\n\n- **[MCP Server Tools](docs/mcp-notes/MCP_SERVER_TOOLS.md)** - Complete tool reference\n- **[LLM-Enhanced Capabilities](docs/mcp-notes/LLM_ENHANCED_CAPABILITIES.md)** - What makes AI interaction unique\n- **[Data Source AI Capabilities](docs/datasource-notes/DATA_SOURCE_AI_CAPABILITIES.md)** - How data search works\n- **[MCPB Build Guide](docs/mcp-notes/MCPB_BUILD_GUIDE.md)** - Building from source\n- **[Netlify Setup](docs/mcp-notes/NETLIFY_SETUP.md)** - Frontend deployment guide\n\n## License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## Support\n\n- **Issues**: Report bugs or request features on [GitHub Issues](https://github.com/aidenlab/juicebox-mcp/issues)\n- **Documentation**: See the `docs/` folder for detailed guides\n\n## Acknowledgments\n\nJuicebox MCP Server is derived from the JavaScript version of [Juicebox.js](https://github.com/aidenlab/juicebox.js), which provides the core Hi-C visualization capabilities.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faidenlab%2Fjuicebox-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faidenlab%2Fjuicebox-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faidenlab%2Fjuicebox-mcp/lists"}