VFB3-MCP Server
A Model Context Protocol (MCP) server for Virtual Fly Brain (VFB): query Drosophila melanogaster neuroanatomy, connectomics, expression and reagent data from Claude, Copilot or any other MCP client.
Canonical repository: VirtualFlyBrain/VFB3-MCP (this one) โ maintained by the Virtual Fly Brain team.
Hosted service: https://mcp.virtualflybrain.org โ no installation, no API key, no account. (The older address https://vfb3-mcp.virtualflybrain.org is the same server and keeps working.)
claude mcp add --transport http virtual-fly-brain https://mcp.virtualflybrain.org
The earlier copy at Robbie1977/VFB3-MCP is archived at v1.3.0 and is not maintained; use this repository and the URL above.
This server provides tools to query VFB data, run queries, and search for terms. In HTTP mode it runs statelessly (no session tracking), so any replica can handle any request and standard load balancing works.
๐ Quick Start
Use the Live Service (Recommended)
The easiest way to use VFB3-MCP is through our hosted service at https://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://mcp.virtualflybrain.org
Configuration JSON (alternative method):
{
"mcpServers": {
"virtual-fly-brain": {
"type": "http",
"url": "https://mcp.virtualflybrain.org",
"tools": ["*"]
}
}
}
Claude Code Setup
-
Locate your Claude configuration file:
- macOS/Linux:
~/.claude.json
- Windows:
%USERPROFILE%\.claude.json
-
Add the VFB3-MCP server to your configuration:
{
"mcpServers": {
"virtual-fly-brain": {
"type": "http",
"url": "https://mcp.virtualflybrain.org",
"tools": ["*"]
}
}
}
- 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://mcp.virtualflybrain.org
- Give it a name like "Virtual Fly Brain"
Alternative JSON configuration (in mcp.json):
{
"servers": {
"virtual-fly-brain": {
"type": "http",
"url": "https://mcp.virtualflybrain.org"
}
}
}
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://mcp.virtualflybrain.org
- Save and restart VS Code if prompted
Other MCP Clients
For any MCP-compatible client that supports HTTP servers:
{
"mcpServers": {
"virtual-fly-brain": {
"type": "http",
"url": "https://mcp.virtualflybrain.org",
"tools": ["*"]
}
}
}
Gemini Setup
To use the Virtual Fly Brain (VFB) Model Context Protocol (MCP) server with Google Gemini, you can connect through custom Python/Node.js clients that support MCP.
Note: Direct Gemini web interface integration with MCP is not currently supported. Developer tools are needed to connect the two.
Option 1: Using Python
For application development, use the mcp and google-genai libraries to connect.
Setup: pip install google-genai mcp
Implementation: Use a streamable HTTP transport in JSON response mode (e.g. enableJsonResponse: true) to connect to the VFB URL, list its tools, and pass their schemas to the Gemini model as Function Declarations.
Testing the Connection
Once configured, you can test that VFB3-MCP is working by asking your AI assistant questions like:
Basic Queries:
- "Get information about the neuron VFB_jrcv0i43"
- "Search for terms related to medulla in the fly brain"
- "What neurons are in the antennal lobe?"
Advanced Queries:
- "Find all neurons that connect to the mushroom body"
- "Show me expression patterns for gene repo"
- "What brain regions are involved in olfactory processing?"
- "Run a connectivity analysis for neuron VFB_00101567"
Search Examples:
- "Search for adult neurons in the visual system"
- "Find genes expressed in the central complex"
- "Show me all templates available in VFB"
If you see responses with VirtualFlyBrain data, including neuron names, brain regions, gene expressions, or connectivity information, the setup is successful!
For more detailed usage examples and API calls, see examples.md.
Example Workflow
- Search for a term: "Search for neurons in the optic lobe"
- Get detailed info: "Get information about VFB_00101567"
- Run specific queries: "Show connectivity for VFB_00101567"
- Explore relationships: "What neurons synapse in the mushroom body?"
The MCP server exposes the following tools (available to assistants like Claude and Copilot):
get_term_info โ Get detailed metadata for a VFB ID
run_query โ Run a precomputed analysis query for a VFB ID (see the Queries field from get_term_info)
search_terms โ Search VFB entities by text with filtering / boosting options. This is the same search virtualflybrain.org itself runs
list_search_facets โ List the facets_annotation type names that search_terms' filter_types / exclude_types / boost_types / demote_types accept, optionally filtered by substring
resolve_entity โ Resolve an unresolved FlyBase-related query string (e.g., P{VT054895-GAL4.DBD} or a driver line / cell type label) to VFB/FlyBase IDs and metadata (not the same as VFB term search)
resolve_combination โ Resolve an unresolved split-GAL4 combination name or synonym into its component IDs
list_connectome_datasets โ List available connectome datasets (e.g., Hemibrain, FAFB)
query_connectivity โ Query connectivity across connectome datasets using upstream/downstream filters, returned as a strongest-first page plus a summary computed over every connection found
get_predicted_neurotransmitters โ Predicted neurotransmitter(s) for a neuron class (and its subclasses) from per-instance connectome predictions, per instance or aggregated with mean confidence, optionally split by dataset
get_known_neurotransmitters โ Known (curated) neurotransmitter(s) for a neuron class and its subclasses, from the ontology classification (no confidence)
get_hierarchy โ Traverse the ontology hierarchy for a VFB ID: part_of (region/tissue structure) and/or subclass_of (cell-type taxonomy), ancestors and/or descendants
lookup_xref โ Map a VFB ID to its external database accessions, or a confirmed external accession (a hemibrain/FAFB/MANC bodyId, a CATMAID skeleton id) back to the VFB term that carries it. Use this rather than search_terms for any accession
combine_queries โ Boolean set algebra (AND, OR, NOT, XOR, โฆ) over the results of two or more queries, with a step trace and a plain-English reading of the expression it parsed
Full parameter documentation for each is in Tool Reference below.
๐ ๏ธ Local Installation
Prerequisites
- Node.js 18 or higher
- npm or yarn
Step-by-Step Installation
-
Clone the repository:
git clone https://github.com/VirtualFlyBrain/VFB3-MCP.git
cd VFB3-MCP
-
Install dependencies:
-
Build the project:
-
Start the server:
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
{
"mcpServers": {
"vfb3-mcp": {
"command": "node",
"args": ["/absolute/path/to/VFB3-MCP/dist/index.js"]
}
}
}
Claude Code
Add to your claude.json file:
{
"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:
For HTTP mode testing:
MCP_MODE=http PORT=3000 node dist/index.js
Docker Installation
Using Docker Compose (Recommended):
docker-compose up --build
Manual Docker Build:
docker build -t vfb3-mcp .
docker run -p 3000:3000 vfb3-mcp
Pull Pre-built Image:
docker pull virtualflybrain/vfb3-mcp:latest
docker run -p 3000:3000 virtualflybrain/vfb3-mcp:latest
get_term_info
Retrieve detailed information about VFB terms using their IDs.
Parameters:
id (string): VFB ID (e.g., "VFB_jrcv0i43")
force_refresh (boolean, optional): Bypass the response cache and recompute (see run_query below for the cost and the whitelisting caveat)
run_query
Execute predefined queries on VFB data.
Parameters:
id (string or array): One or more VFB IDs (e.g., "VFB_00101567")
query_type (string): Query type from the entity's Queries array (e.g., "PaintedDomains")
queries (array, optional): {id, query_type} pairs for mixed batch queries
limit (number, optional): Max rows per call (default 25). The true total is always returned as count; use 0 for all rows (still capped ~25000)
offset (number, optional): Row offset for paging (default 0); re-run with offset += limit for the next page
include_images (boolean, optional): Include the thumbnail column (default false โ it is stripped to save space, and the response _note says how to re-add it)
force_refresh (boolean, optional): Bypass the response cache and recompute. Expensive; intended only as a one-shot retry of a call that returned a stale or failed result. A failed query is already retried once automatically. Requires the server's egress IP to be whitelisted on v3-cached โ from a non-whitelisted host nginx ignores the header and serves the cached entry unchanged.
The response reports count_status alongside count: exact (count is the true total), row_count (no total supplied โ count is just the rows returned), or unavailable (the query failed upstream and count is -1). A -1 is an error indication, not an empty result set, and _note says so in words.
FlyBase stocks and split-GAL4 combination publications are run_query query_types too: FindStocks and FindComboPublications. FindStocks takes FlyBase feature, stock and strain (FBsn) IDs. For a split combination (FBco), FindStocks returns stocks with both hemidrivers where they exist, and otherwise falls back to stocks of each hemidriver; a match column says which.
search_terms
Search for VFB terms. This calls VFBquery's /search, which is the search virtualflybrain.org itself runs โ the same Solr query, the same filters and boosts, the same final sort โ so a result here is the result a user would see on the site. Deprecated terms are already excluded server-side; there is no need to ask for that.
Parameters:
query (string): Search query (e.g., "medulla")
filter_types (array, optional): Keep only results matching ALL of these facets_annotation types (AND logic)
exclude_types (array, optional): Drop results matching ANY of these facets_annotation types (OR logic)
boost_types (array, optional): Lift results matching these types up the ranking without excluding others
demote_types (array, optional): Sink results matching these types to the bottom of the ranking without excluding them. Ignored for a type that also appears in boost_types
unique (boolean, optional): One row per term (default true). Set false for one row per matching synonym, which shows which name matched at the cost of repeating IDs
start (number, optional): Page start index (default 0)
rows (number, optional): Rows to return (default 150, max 1000)
minimize_results (boolean, optional): Return only the top 10 with reduced fields, for a first look (default false)
auto_fetch_term_info (boolean, optional): When the query matches one term's name exactly, also fetch that term's info (default false)
Type names come from the live vocabulary โ there are over 200 of them and they change as data is added, so call list_search_facets rather than guessing. The response reports returned (rows given), total (length of the ranked list), distinct_terms and solr_matches (terms Solr matched before ranking) separately, so a truncated page never looks like a small result set.
list_search_facets
List the valid facets_annotation type names for the four type filters above, read from the live vocabulary.
Parameters:
contains (string, optional): Case- and separator-insensitive substring filter (e.g., "neuron", "nervous system")
If the deployed VFBquery predates the /facets endpoint, this falls back to a snapshot bundled with the server and says so โ names absent from a snapshot result may still be valid.
query_connectivity
Query synaptic connectivity between neuron classes across all connectome datasets. At least one of upstream_type or downstream_type is required. Results are ranked strongest-first and paged: you get limit rows plus a summary computed over every connection found โ weight min/max/total/mean, per-dataset counts, distinct neuron counts, and the top class pairs โ so the totals stay true even though the rows are truncated. A broad query can find tens of thousands of connections, which is why paging is on by default.
Parameters:
upstream_type / downstream_type (string, optional): Neuron class OWL ID or label. Anatomical regions are not accepted
weight (number, optional): Minimum synapse count (recommended 5; use โฅ50 when both ends are specified)
group_by_class (boolean, optional): Aggregate to class pairs instead of neuron pairs โ usually the better first call on a broad query
exclude_dbs (array, optional): Dataset symbols to exclude (recommended ["hb","fafb"]); see list_connectome_datasets
limit (number, optional): Rows to return, strongest first (default 50; 0 for all)
offset (number, optional): Row to start from within the ranking (default 0)
get_predicted_neurotransmitters
Predicted neurotransmitter(s) for a neuron class โ itself or any subclass โ from per-instance connectome predictions (each reconstructed neuron carries a predicted transmitter with a confidence). Aggregated to flat per-class rows by default (one per cell type ร neurotransmitter, with instances, percent_of_class, mean_confidence); aggregate=false gives one row per neuron. split_by_dataset=true adds a dataset column so agreement across connectomes is visible. The neurotransmitter is a GO secretion term (nt_id/nt_label) โ the same id space as get_known_neurotransmitters. Distinct from get_known_neurotransmitters, which is the curated classification without confidence.
Parameters:
neuron_type (string, required): Neuron class OWL ID or label (means the class and its subclasses)
aggregate (boolean, optional): true (default) for per-class rows; false for per-instance rows
split_by_dataset (boolean, optional): true (aggregate only) for one row per (cell type, neurotransmitter, dataset)
exclude_dbs (array, optional): Dataset symbols to exclude (default ["hb","fafb"]; [] for all)
min_confidence (number, optional): Drop predictions below this confidence (0..1)
get_known_neurotransmitters
Known (curated) neurotransmitter(s) for a neuron class and its subclasses, from the ontology's classification rather than per-instance predictions โ so no confidence. One row per (cell type, neurotransmitter): {cell_type_id, cell_type, nt_id, nt_label}, with nt_id a GO secretion term. Empty when the ontology asserts none (try get_predicted_neurotransmitters for the data-driven answer).
Parameters:
neuron_type (string, required): Neuron class OWL ID or label (means the class and its subclasses)
resolve_entity
Resolve an unresolved FlyBase-related query string into VFB/FlyBase IDs and metadata. This is not VFB term search: it takes the raw text a user wrote and works down a tiered resolution (exact name โ synonym โ broad pattern match). Pass driver lines, transgene names, cell-type labels and gene symbols โ P{VT054895-GAL4.DBD}, Hb9-GAL4, SS04495, MB002B, PAM cluster, dpp.
Parameters:
name (string): The unresolved string, exactly as the user wrote it
Do not pass an ID you already have โ an FBgn/FBal/FBti/FBco/FBst or a VFB ID goes straight to the downstream tool. For stocks, the downstream tool is run_query with query_type: "FindStocks".
resolve_combination
Resolve an unresolved split-GAL4 combination name or synonym to its FBco ID and component hemidrivers, using the same tiered resolution as resolve_entity.
Parameters:
name (string): The combination name or synonym as written (e.g. MB002B, SS04495)
Do not pass an FBco ID you already have. For that combination's publications, use run_query with query_type: "FindComboPublications".
list_connectome_datasets
List the available connectome datasets with their labels and symbols. Takes no parameters. Call it when you need valid dataset symbols โ they are what query_connectivity's exclude_dbs accepts. Common ones are Hemibrain (hb), FAFB (fafb) and MANC.
get_hierarchy
Build a hierarchy tree for a VFB term, showing ancestors (parents) and/or descendants (children). Descendants come back as a nested tree for both relationship types; ancestors come back as a nested chain, filtered to nervous-system terms for part_of.
Parameters:
id (string): VFB term ID (e.g. FBbt_00005801 for mushroom body)
relationship (string): part_of for brain-region structure ("what are the parts of the mushroom body?"), subclass_of for cell-type taxonomy ("what types of Kenyon cell are there?")
direction (string, optional): descendants, ancestors or both (default both)
max_depth (number, optional): Levels to expand; 1 = direct children/parents only (default 1). -1 is the full tree โ use with care on a broad term
Start at max_depth: 1 and offer to go deeper rather than expanding a whole subtree unasked.
lookup_xref
Map a VFB ID to its external database accessions, or an external accession back to the VFB term that carries it.
Use this rather than search_terms for any external accession โ a hemibrain/FAFB/MANC bodyId, a CATMAID skeleton id, a neuprint id. Free-text search on a bare number ranks a plausible near-miss first and offers no way to tell a real match from a good guess; this endpoint confirms the accession against each candidate term's own cross-reference list and returns a row only if that term really carries it.
Parameters:
id (string, optional): A VFB ID whose external accessions you want (e.g. VFB_jrchjtdb)
accession (string, optional): An external accession to resolve back to a VFB term (e.g. 1734350908)
db (string, optional): Site filter. Matches a symbol (hb), a short_form (neuprint_JRC_Hemibrain_1point2point1) or a label, ignoring case, punctuation and spacing, and also accepts whole words from those names โ flywire, hemibrain, neuprint, catmaid, male-cns all work
Pass exactly one of id or accession. Each row carries id, label, db, db_label, site_id, accession, is_data_source and a resolved deep link into the external site.
The two directions do not mean the same thing when they come back empty, and the response says which you are looking at:
id_to_accession โ one document fetch against the term's own cross-reference list. Empty is authoritative: this term has no cross-references.
accession_to_id โ a search followed by an exact confirmation. Empty means no indexed term carrying that accession was reached, not that none exists. An accession is searchable only because VFB writes it into the term label (DA1_lPN_R (FlyEM-HB:1734350908)), so connectome bodyIds resolve while an accession from a link-out-only site will not. Report it as "could not confirm", and do not fall back to a search result as though it were a match.
combine_queries
Boolean set algebra over the results of two or more queries, compared on term ID. Answers "which neurons are in both X and Y", "in X but not Y", "in either but not both".
Use this rather than running the queries separately and intersecting them yourself. Operands are routinely hundreds or thousands of rows each; the server does the comparison in about a second and returns the answer with its own audit trail.
Parameters:
expr (string): The expression over your operand names โ calyx AND lh, calyx but not lh, (a OR b) AND NOT c. Max 2000 characters
operands (object): Named sets referenced by expr. Each value is "<QueryType>:<id>" (any run_query query type), "search:<text>", or "ids:<id>,<id>" for a literal set. Max 12 operands
universe (string, optional): Operand spec defining what "everything" means for a complement. Defaults to the union of the operands
limit (number, optional): Rows to return (default 25). count is always the true size of the result set; 0 returns every row
include_images (boolean, optional): Include the thumbnail column (default false โ on a 220-row result it is the difference between 428 KB and 9.5 KB)
explain_only (boolean, optional): Parse and explain without running any query (default false)
require_complete (boolean, optional): Fail rather than answer if any operand was truncated (default false)
Operators: AND OR NOT XOR NAND NOR XNOR, unary NOT, brackets, symbol aliases (& | - ^) and plain-English aliases ("but not", "in both", "either but not both"). Precedence, loosest first: OR/NOR, then XOR/XNOR, then AND/NAND/NOT, all left-associative.
The response explains itself: as_read gives the grouping actually parsed, plain_english reads the whole expression back, steps traces the size of every intermediate set, operands reports what each one returned, and warnings flags the three ways a combination is silently wrong โ a truncated operand, two sides in different ID namespaces, and a complement against an implicit universe. Check as_read against what was asked before reporting the answer; explain_only: true shows the parse for under a kilobyte and no query cost.
There is no offset. Upstream reserves the name but does not implement it, so raise limit instead of paging.
๐ง 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
๐ License
MIT