VFB3-MCP
OfficialThis server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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.orgThe 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.jsonWindows:
%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.orgGive 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-brainURL:
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?"
Related MCP server: VFB3-MCP
🛠️ Available Tools
The MCP server exposes the following tools (available to assistants like Claude and Copilot):
get_term_info— Get detailed metadata for a VFB IDrun_query— Run a precomputed analysis query for a VFB ID (see theQueriesfield fromget_term_info)search_terms— Search VFB entities by text with filtering / boosting options. This is the same search virtualflybrain.org itself runslist_search_facets— List thefacets_annotationtype names thatsearch_terms'filter_types/exclude_types/boost_types/demote_typesaccept, optionally filtered by substringresolve_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 IDslist_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 foundget_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 datasetget_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/orsubclass_of(cell-type taxonomy), ancestors and/or descendantslookup_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 thansearch_termsfor any accessioncombine_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-MCPInstall dependencies:
npm installBuild the project:
npm run buildStart the server:
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
{
"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) orCtrl + Shift + P(Windows/Linux)Select MCP: Add server…
Choose Command type
Enter:
Name:
vfb3-mcpCommand:
nodeArguments:
/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:
http://localhost:3000For HTTP mode testing:
MCP_MODE=http PORT=3000 node dist/index.jsDocker Installation
Using Docker Compose (Recommended):
docker-compose up --buildManual Docker Build:
# Build the image
docker build -t vfb3-mcp .
# Run the container
docker run -p 3000:3000 vfb3-mcpPull Pre-built Image:
docker pull virtualflybrain/vfb3-mcp:latest
docker run -p 3000:3000 virtualflybrain/vfb3-mcp:latest📋 Tool Reference
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 (seerun_querybelow 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'sQueriesarray (e.g., "PaintedDomains")queries(array, optional):{id, query_type}pairs for mixed batch querieslimit(number, optional): Max rows per call (default 25). The true total is always returned ascount; use 0 for all rows (still capped ~25000)offset(number, optional): Row offset for paging (default 0); re-run withoffset += limitfor the next pageinclude_images(boolean, optional): Include thethumbnailcolumn (default false — it is stripped to save space, and the response_notesays 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 othersdemote_types(array, optional): Sink results matching these types to the bottom of the ranking without excluding them. Ignored for a type that also appears inboost_typesunique(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 IDsstart(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 acceptedweight(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 queryexclude_dbs(array, optional): Dataset symbols to exclude (recommended["hb","fafb"]); seelist_connectome_datasetslimit(number, optional): Rows to return, strongest first (default 50;0for 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;falsefor per-instance rowssplit_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_00005801for mushroom body)relationship(string):part_offor brain-region structure ("what are the parts of the mushroom body?"),subclass_offor cell-type taxonomy ("what types of Kenyon cell are there?")direction(string, optional):descendants,ancestorsorboth(defaultboth)max_depth(number, optional): Levels to expand; 1 = direct children/parents only (default 1).-1is 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), ashort_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-cnsall 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 charactersoperands(object): Named sets referenced byexpr. Each value is"<QueryType>:<id>"(anyrun_queryquery type),"search:<text>", or"ids:<id>,<id>"for a literal set. Max 12 operandsuniverse(string, optional): Operand spec defining what "everything" means for a complement. Defaults to the union of the operandslimit(number, optional): Rows to return (default 25).countis always the true size of the result set;0returns every rowinclude_images(boolean, optional): Include thethumbnailcolumn (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
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
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
MCP server for Drosophila neuroscience data from VirtualFlyBrain
Connect AI clients to biomedical data and tools.
MCP server for querying BrainKB, a knowledge base for neuroscience knowledge graphs.
Turn any LLM into your lab assistant: search samples, track experiments, analyze data with AI.
Related MCP Servers
- AlicenseAqualityBmaintenanceA high-performance MCP server that gives LLMs access to 25 biomedical tools federated across 50+ upstream APIs for genes, variants, drugs, diseases, literature, clinical trials, and structural biology.43138 npm12Apache 2.0
- AlicenseNot gradedqualityFmaintenanceEnables AI assistants to query VirtualFlyBrain data, run queries, and search for terms related to Drosophila neurobiology.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to browse the Gene Ontology through the EBI QuickGO API, including keyword search for GO terms, retrieval of a term's name, aspect, definition and synonyms by id, and listing the GO annotations tied to a UniProt accession. Runs keyless over HTTP or as a local stdio server, with an optional gateway route that lets plain-English questions be answered without choosing tools manually.81 npmMIT
- AlicenseAqualityCmaintenanceEnables LLM agents to search EMDB cryo-EM maps, look up UniProt proteins, compute ESM-2 sequence embeddings, retrieve cryo-EM maps from a protein sequence via a two-tower model, and search GEO DNA-methylation arrays, all through typed tools with structured output. Ships with a 40-question evaluation harness that runs Claude as the MCP client.3MIT