org.virtualflybrain/vfb3-mcp

Official3 tools

by Robbie1977 · TypeScript

VirtualFlyBrain

MCP server for Drosophila neuroscience data from VirtualFlyBrain

Access Drosophila neuroscience data and connectome information from VirtualFlyBrain.

Captured live from the server via tools/list.

get_term_info

Get term information from VirtualFlyBrain using one or more VFB IDs. Supports batch requests — pass an array of IDs to fetch multiple terms in parallel. When multiple IDs are provided, results are returned as a JSON object keyed by ID. The Images field is keyed by template brain ID — use these to construct VFB browser URLs: https://v2.virtualflybrain.org/org.geppetto.frontend/geppetto?id=<VFB_ID>&i=<TEMPLATE_ID>,<IMAGE_ID1>,<IMAGE_ID2> where id= is the focus term and i= is a comma-separated list of image IDs for the 3D viewer (template ID must be first in the i= list to set the coordinate space).

Parameters (1)

idanyrequired
One or more VFB IDs to look up

run_query

Run a query on VirtualFlyBrain using a VFB ID and query type. Supports batch requests — pass an array of IDs to run the same query_type on all of them, or use the queries array for mixed ID/query_type combinations. When multiple queries are provided, results are returned as a JSON object keyed by "ID::query_type". IMPORTANT: Do NOT pass tool names (like "get_term_info" or "search_terms") as query_type — those are separate tools. Valid query_types are returned by get_term_info in the Queries array for each entity. Common query_types include: PaintedDomains, AllAlignedImages, AlignedDatasets, AllDatasets (for templates); SimilarMorphologyTo, NeuronInputsTo, NeuronNeuronConnectivityQuery (for neurons); ListAllAvailableImages, SubclassesOf, PartsOf, NeuronsPartHere, NeuronsSynaptic, ExpressionOverlapsHere (for classes). Available query_types vary by entity type — ALWAYS call get_term_info FIRST to see which queries are available for a given ID, as attempting invalid query types will result in an error message directing you to use get_term_info.

Parameters (3)

idany
One or more VFB IDs to query
query_typestring
A valid query type from the Queries array returned by get_term_info. Used for single id or array of ids.
queriesarray
Array of {id, query_type} pairs for mixed batch queries. When provided, id and query_type params are ignored.

search_terms

Search for VFB terms using the Solr search server. Results can be filtered, excluded, or boosted by entity type using facets_annotation values. Available filter types: entity, anatomy, nervous_system, individual, has_image, adult, cell, neuron, vfb, has_neuron_connectivity, nblast, visual_system, cholinergic, class, secondary_neuron, expression_pattern, gabaergic, expression_pattern_fragment, glutamatergic, feature, sensory_neuron, neuronbridge, deprecated, larva, has_region_connectivity, nblastexp, gene, primary_neuron, flycircuit, mechanosensory_system, histaminergic, lineage_mbp, peptidergic, hasscrnaseq, chemosensory_system, split, has_subclass, olfactory_system, dopaminergic, fafb, l1em, pub, enzyme, motor_neuron, cluster, lineage_6, lineage_3, serotonergic, lineage_19, lineage_cm3, lineage_dm6, proprioceptive_system, gustatory_system, sense_organ, lineage_mbp4, lineage_mbp1, lineage_1, lineage_mbp2, lineage_all1, lineage_balc, lineage_cm4, lineage_dm4, muscle, lineage_13, lineage_8, lineage_mbp3, lineage_12, lineage_dm1, lineage_dpmm1, lineage_9, lineage_cp2, lineage_dl1, fanc, lineage_7, lineage_vpnd2, lineage_dm3, lineage_dpmpm2, lineage_14, lineage_4, lineage_blp1, lineage_dalv2, lineage_eba1, lineage_dm2, lineage_dpmpm1, auditory_system, lineage_16, lineage_blvp1, lineage_blav2, lineage_vlpl2, lineage_alad1, lineage_bamv3, lineage_bld6, lineage_vpnd1, synaptic_neuropil, lineage_23, lineage_17, lineage_10, lineage_dplpv, lineage_21, lineage_alv1 Multiple filter_types are ANDed (results must match ALL). Multiple exclude_types are ORed (any match excludes). boost_types soft-rank matching results higher without excluding others.

Parameters (8)

querystringrequired
Search query (e.g., medulla)
filter_typesarray
Filter results to only include items matching ALL of these facets_annotation types (AND logic)
exclude_typesarray
Exclude results matching ANY of these facets_annotation types (OR logic)
boost_typesarray
Boost ranking of results matching these facets_annotation types without excluding others
startnumber
Pagination start index (default 0) - use to get results beyond the first page
rowsnumber
Number of results to return (default 150, max 1000) - use smaller numbers for focused searches
minimize_resultsboolean
When true, limit results to top 10 for initial searches and add truncation metadata. For exact matches, return only the matching result.
auto_fetch_term_infoboolean
When true and an exact label match is found, automatically fetch and include term info in the response.

README.md5 KBView on GitHub

VFB3-MCP Server

A Model Context Protocol (MCP) server for interacting with VirtualFlyBrain (VFB) APIs. This server provides tools to query VFB data, run queries, and search for terms.

🚀 Quick Start

Use the Live Service (Recommended)

The easiest way to use VFB3-MCP is through our hosted service at https://vfb3-mcp.virtualflybrain.org. This requires no installation or setup on your machine.

Claude Desktop Setup

Open Claude Desktop and go to Settings
Navigate to the MCP section
Add a new MCP server with these settings:
- Server Name: virtual-fly-brain (or any name you prefer)
- Type: HTTP
- Server URL: https://vfb3-mcp.virtualflybrain.org

Configuration JSON (alternative method):

json

{
  "mcpServers": {
    "virtual-fly-brain": {
      "url": "https://vfb3-mcp.virtualflybrain.org"
    }
  }
}

Claude Code Setup

Locate your Claude configuration file:
- macOS/Linux: ~/.claude.json
- Windows: %USERPROFILE%\.claude.json
Add the VFB3-MCP server to your configuration:

json

{
  "mcpServers": {
    "virtual-fly-brain": {
      "url": "https://vfb3-mcp.virtualflybrain.org"
    }
  }
}

Restart Claude Code for changes to take effect

GitHub Copilot Setup

Open VS Code with GitHub Copilot installed
Open Settings (Ctrl/Cmd + ,)
Search for "MCP" in the settings search
Find the MCP Servers setting
Add the server URL: https://vfb3-mcp.virtualflybrain.org
Give it a name like "Virtual Fly Brain"

Visual Studio Code (with MCP Extension)

Install the MCP extension for VS Code from the marketplace
Open the Command Palette (Ctrl/Cmd + Shift + P)
Type "MCP: Add server" and select it
Choose "HTTP" as the server type
Enter the server details:
- Name: virtual-fly-brain
- URL: https://vfb3-mcp.virtualflybrain.org
Save and restart VS Code if prompted

Other MCP Clients

For any MCP-compatible client that supports HTTP servers:

json

{
  "mcpServers": {
    "virtual-fly-brain": {
      "url": "https://vfb3-mcp.virtualflybrain.org",
      "type": "http"
    }
  }
}

Testing the Connection

Once configured, you can test that VFB3-MCP is working by asking your AI assistant to:

"Get information about the term VFB_jrcv0i43"
"Search for terms related to medulla"
"Run a PaintedDomains query for VFB_00101567"

If you see responses with VirtualFlyBrain data, the setup is successful!

🛠️ Local Installation

Prerequisites

Node.js 18 or higher
npm or yarn

Step-by-Step Installation

Clone the repository:

bash

git clone https://github.com/Robbie1977/VFB3-MCP.git
cd VFB3-MCP

Install dependencies:
bash
```
npm install
```
Build the project:
bash
```
npm run build
```
Start the server:
bash
```
npm start
```

Platform-Specific Setup

Claude Desktop (Local Development)

For local development with Claude Desktop, add this to your MCP configuration:

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

json

{
  "mcpServers": {
    "vfb3-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/VFB3-MCP/dist/index.js"]
    }
  }
}

Claude Code

Add to your claude.json file:

json

{
  "mcpServers": {
    "vfb3-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/VFB3-MCP/dist/index.js"]
    }
  }
}

Visual Studio Code

Install the MCP extension for VS Code
Press Cmd + Shift + P (macOS) or Ctrl + Shift + P (Windows/Linux)
Select MCP: Add server…
Choose Command type
Enter:
- Name: vfb3-mcp
- Command: node
- Arguments: /absolute/path/to/VFB3-MCP/dist/index.js

GitHub Copilot

Configure the MCP server URL in your Copilot settings to point to your local server:

code

http://localhost:3000

For HTTP mode testing:

bash

MCP_MODE=http PORT=3000 node dist/index.js

Docker Installation

Using Docker Compose (Recommended):

bash

docker-compose up --build

Manual Docker Build:

bash

# Build the image
docker build -t vfb3-mcp .

# Run the container
docker run -p 3000:3000 vfb3-mcp

Pull Pre-built Image:

bash

docker pull virtualflybrain/vfb3-mcp:latest
docker run -p 3000:3000 virtualflybrain/vfb3-mcp:latest

Available Tools

get_term_info

Retrieve detailed information about VFB terms using their IDs.

Parameters:

id (string): VFB ID (e.g., "VFB_jrcv0i43")

run_query

Execute predefined queries on VFB data.

Parameters:

id (string): VFB ID (e.g., "VFB_00101567")
query_type (string): Type of query (e.g., "PaintedDomains")

search_terms

Search for VFB terms using the Solr search server.

Parameters:

query (string): Search query (e.g., "medulla")

🧠 About VirtualFlyBrain

VirtualFlyBrain (VFB) is a comprehensive knowledge base about Drosophila melanogaster neurobiology, providing 3D images, gene expression data, neural connectivity information, and standardized terminology for fly brain research.

📖 Documentation

LLM Guidance: Guide for AI assistants on using this MCP effectively
Examples: Usage examples and integration guides
Technical Documentation: Infrastructure, deployment, and development details

📄 License

MIT

Install

claude_desktop_config.json

{
  "mcpServers": {
    "vfb3-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://vfb3-mcp.virtualflybrain.org"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.