VirtualFlyBrain

Official11 tools

by VirtualFlyBrain · TypeScript

MCP server for Drosophila neuroscience data from VirtualFlyBrain

org.virtualflybrain/vfb3-mcp is an MCP server for Virtual Fly Brain (VFB). It provides tools for querying Drosophila melanogaster neuroanatomy, connectomics, expression data, and reagent data through MCP clients. It is designed to be used from clients like Claude or Copilot.

🛠️ Key Features

MCP server for Virtual Fly Brain (VFB)
Query Drosophila melanogaster neuroanatomy
Query connectomics, expression, and reagent data
Tool support: 9 tools

🚀 Use Cases

Retrieve VFB neuroanatomy information
Explore connectomics relationships
Look up expression and reagent data for Drosophila research

⚡ Developer Benefits

Works with any MCP client
Hosted service available without installation
No API key or account required
Canonical repository: VirtualFlyBrain/VFB3-MCP

⚠️ Limitations

Coverage is limited to Drosophila neuroscience data from Virtual Fly Brain (VFB)

Topics

drosophila-melanogastermcpmcp-serverconnectomicsllmneuroscienceontologyvirtualflybrain

Captured live from the server via tools/list.

get_term_info

Get term info for a VFB or anatomy ontology entity (VFB_*, FBbt_*, etc.). THIS IS THE QUERY DISCOVERY TOOL: the response's "Queries" array lists the valid query_type values that run_query accepts for this entity. ALWAYS call get_term_info before run_query unless you already obtained the query_type from a previous get_term_info call in this conversation. Returns: SuperTypes (classification), Tags (data flags like has_image, has_neuron_connectivity), Queries (valid query_types for run_query), RelatedTools (other MCP tools applicable to this entity, with default_args ready to copy — e.g. get_hierarchy with subclass_of for cell types or part_of for nervous-system regions), Images (keyed by template brain ID), Publications, Synonyms. Supports batch — pass an array of IDs to fetch in parallel; batch results are returned as a JSON object keyed by ID. To build VFB browser URLs from the Images field: https://v2.virtualflybrain.org/org.geppetto.frontend/geppetto?id=<VFB_ID>&i=<TEMPLATE_ID>,<IMAGE_ID1>,<IMAGE_ID2> — id= sets the focus term and i= lists images for the 3D viewer (template ID must be first in i= to set the coordinate space).

Parameters2

id	any	required	One or more VFB IDs to look up
force_refresh	boolean	optional	Bypass the response cache and recompute this result. Expensive — leave it unset on a first call. Set it ONLY to re-try a call that, earlier in this same conversation, returned a result that was clearly wrong, stale, or reported as failed. Never set it on more than one retry of the same call.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "oneOf": [
        {
          "type": "string",
          "description": "A single VFB ID (e.g., VFB_jrcv0i43)"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "An array of VFB IDs to fetch in batch (e.g., [\"VFB_jrcv0i43\", \"VFB_00101567\"])"
        }
      ],
      "description": "One or more VFB IDs to look up"
    },
    "force_refresh": {
      "type": "boolean",
      "description": "Bypass the response cache and recompute this result. Expensive — leave it unset on a first call. Set it ONLY to re-try a call that, earlier in this same conversation, returned a result that was clearly wrong, stale, or reported as failed. Never set it on more than one retry of the same call."
    }
  },
  "required": [
    "id"
  ]
}

run_query

Run a pre-computed query on a VFB entity. REQUIRED WORKFLOW: (1) call get_term_info on the ID first; (2) read the response's "Queries" array; (3) pass one of those values as query_type. Calling run_query with a guessed query_type will return an error. If a query returns empty rows or an error, the entity does not support that query_type or has no data for it — try a different query_type from the Queries array, or try a related entity (e.g. its parent class via get_hierarchy). Empty results do NOT mean the answer is unknown — only that this call did not return it. NEVER fabricate results from training data when a query is empty; tell the user clearly what was tried. NEVER pass tool names like "get_term_info" or "search_terms" as query_type — those are separate tools. Common query_types by entity kind: PaintedDomains, AllAlignedImages, AlignedDatasets, AllDatasets (templates); SimilarMorphologyTo, NeuronInputsTo, NeuronNeuronConnectivityQuery, NeuronRegionConnectivityQuery (individual neurons); ListAllAvailableImages, SubclassesOf, PartsOf, NeuronsPartHere, NeuronsSynaptic, ExpressionOverlapsHere, DownstreamClassConnectivity, UpstreamClassConnectivity (classes). Supports batch — pass an array of IDs (same query_type) or a "queries" array of {id, query_type} pairs; batch results are keyed by "ID::query_type". Results are PAGED: the first 25 rows by default (change with limit/offset) plus the true total as "count". ALWAYS read "count_status" before quoting "count": "exact" means count is the true total; "unavailable" means the query FAILED upstream and count is -1, which is NOT zero and must never be reported as "no results" — read "_note" and tell the user the query could not be run. Image/thumbnail columns are excluded by default to save space - pass include_images=true to include them. FlyBase integration is via query_types too: FindStocks (fly stocks for a FlyBase feature ID - FBgn/FBal/FBti/FBtp/FBco/FBst) and FindComboPublications (publications for an FBco split-GAL4 combination). Get those IDs from resolve_entity / resolve_combination first, then run_query with the ID and the query_type. Include FlyBase links in output: https://flybase.org/reports/{ID}.

Parameters7

id	any	optional	One or more VFB IDs to query
query_type	string	optional	A valid query type from the Queries array returned by get_term_info. Used for single id or array of ids.
queries	array	optional	Array of {id, query_type} pairs for mixed batch queries. When provided, id and query_type params are ignored.
limit	number	optional	Max rows returned per call (default 25). The true total is always returned as "count"; broad queries (e.g. ListAllAvailableImages, or NeuronsSynaptic on a whole region) can have thousands to hundreds of thousands of rows. Use 0 for all rows (still capped server-side ~25000 - avoid for broad queries).
offset	number	optional	Row offset for paging (default 0). To get the next page, re-run with offset increased by limit; "count" gives the total.
include_images	boolean	optional	Include the image/thumbnail column in result rows. Default false: the thumbnail is a long markdown image string that is rarely useful to reason over and greatly inflates every row, so it is stripped and the response says so in _note. Set true to include it (e.g. to build image URLs).
force_refresh	boolean	optional	Bypass the response cache and recompute this result. Expensive — leave it unset on a first call. Set it ONLY to re-try a call that, earlier in this same conversation, returned a result that was clearly wrong, stale, or reported as failed. Never set it on more than one retry of the same call. A failed query (count -1) is already retried once automatically, so you do not need this for that case.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "oneOf": [
        {
          "type": "string",
          "description": "A single VFB ID (e.g., VFB_00101567)"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "An array of VFB IDs — all will use the same query_type"
        }
      ],
      "description": "One or more VFB IDs to query"
    },
    "query_type": {
      "type": "string",
      "description": "A valid query type from the Queries array returned by get_term_info. Used for single id or array of ids."
    },
    "queries": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "VFB ID"
          },
          "query_type": {
            "type": "string",
            "description": "Query type for this ID"
          }
        },
        "required": [
          "id",
          "query_type"
        ]
      },
      "description": "Array of {id, query_type} pairs for mixed batch queries. When provided, id and query_type params are ignored."
    },
    "limit": {
      "type": "number",
      "description": "Max rows returned per call (default 25). The true total is always returned as \"count\"; broad queries (e.g. ListAllAvailableImages, or NeuronsSynaptic on a whole region) can have thousands to hundreds of thousands of rows. Use 0 for all rows (still capped server-side ~25000 - avoid for broad queries)."
    },
    "offset": {
      "type": "number",
      "description": "Row offset for paging (default 0). To get the next page, re-run with offset increased by limit; \"count\" gives the total."
    },
    "include_images": {
      "type": "boolean",
      "description": "Include the image/thumbnail column in result rows. Default false: the thumbnail is a long markdown image string that is rarely useful to reason over and greatly inflates every row, so it is stripped and the response says so in _note. Set true to include it (e.g. to build image URLs)."
    },
    "force_refresh": {
      "type": "boolean",
      "description": "Bypass the response cache and recompute this result. Expensive — leave it unset on a first call. Set it ONLY to re-try a call that, earlier in this same conversation, returned a result that was clearly wrong, stale, or reported as failed. Never set it on more than one retry of the same call. A failed query (count -1) is already retried once automatically, so you do not need this for that case."
    }
  }
}

search_terms

Search VFB terms. This is the search virtualflybrain.org itself runs — the same Solr query, the same ranking — so what comes back first here is what a user would see first on the site. USE filter_types BY DEFAULT. Unfiltered searches mix scRNAseq artifacts and developmental stages in with the entity the user wants. Common filter_types recipes: - Neuron classes: ["neuron", "class"] - Individual neurons with images: ["neuron", "has_image"] - Neurons with connectome data: ["neuron", "has_neuron_connectivity"] - Brain regions / neuropils: ["anatomy"] - Genes: ["gene"] - Driver lines / expression patterns: ["expression_pattern"] - Datasets: ["dataset"] There are over 200 type names and they change as data is added, so do NOT guess them: call list_search_facets to see the current vocabulary (optionally filtered, e.g. contains="lineage"). Names are matched case- and separator-insensitively, and a name that does not exist is an error with suggestions rather than a silently empty result. Deprecated terms are excluded by the search itself — you do not need exclude_types: ["deprecated"], and adding it is harmless but pointless. Stage filtering: VFB covers adult, larval, and embryonic data, and many anatomical FBbt classes are stage-agnostic. Do NOT add "adult" or "larva" to filter_types by default — only add them when the user is explicit about a stage (e.g. "adult Kenyon cells", "larval mushroom body"). Default searches should leave stage out so stage-agnostic classes and all life stages are visible. Useful flags: - unique=true (the default) → one row per term. Turn it OFF only when you need to see WHICH synonym matched; with unique=false a term appears once per matching synonym, so "Kenyon cell" can return the same ID several times. - minimize_results=true → top 10, essential fields only, for exploratory searches. - auto_fetch_term_info=true → if an exact label match is found, returns get_term_info in the same response. - boost_types=["has_image", "has_neuron_connectivity"] → float data-rich entities to the top of the list without excluding anything else. - demote_types=["expression_pattern_fragment"] → sink noisy types to the bottom of the list instead of removing them. If the search returns no good matches, do NOT fall back to training-data answers — try alternative spellings, synonyms, broader terms, or different filter_types. Multiple filter_types are ANDed (results must match ALL). Multiple exclude_types are ORed (any match excludes). boost_types and demote_types re-order without excluding; boost wins if a term matches both.

Parameters10

query	string	required	Search query (e.g., medulla)
filter_types	array	optional	Filter results to only include items matching ALL of these facets_annotation types (AND logic). Use list_search_facets for valid names.
exclude_types	array	optional	Exclude results matching ANY of these facets_annotation types (OR logic). Deprecated terms are already excluded.
boost_types	array	optional	Float results matching these facets_annotation types to the top of the ranked list without excluding others
demote_types	array	optional	Sink results matching these facets_annotation types to the bottom of the ranked list without excluding them. Ignored for a type that also appears in boost_types.
unique	boolean	optional	One row per term (default true). Set false to get a row per matching synonym, which shows WHICH name matched at the cost of repeating IDs.
start	number	optional	Pagination start index (default 0) - use to get results beyond the first page
rows	number	optional	Number of results to return (default 150, max 1000) - use smaller numbers for focused searches
minimize_results	boolean	optional	When true, return at most 10 results with only the essential fields. For exact matches, return only the matching result.
auto_fetch_term_info	boolean	optional	When true and an exact label match is found, automatically fetch and include term info in the response.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search query (e.g., medulla)"
    },
    "filter_types": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Filter results to only include items matching ALL of these facets_annotation types (AND logic). Use list_search_facets for valid names."
    },
    "exclude_types": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Exclude results matching ANY of these facets_annotation types (OR logic). Deprecated terms are already excluded."
    },
    "boost_types": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Float results matching these facets_annotation types to the top of the ranked list without excluding others"
    },
    "demote_types": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Sink results matching these facets_annotation types to the bottom of the ranked list without excluding them. Ignored for a type that also appears in boost_types."
    },
    "unique": {
      "type": "boolean",
      "description": "One row per term (default true). Set false to get a row per matching synonym, which shows WHICH name matched at the cost of repeating IDs.",
      "default": true
    },
    "start": {
      "type": "number",
      "description": "Pagination start index (default 0) - use to get results beyond the first page",
      "default": 0
    },
    "rows": {
      "type": "number",
      "description": "Number of results to return (default 150, max 1000) - use smaller numbers for focused searches",
      "default": 150,
      "maximum": 1000
    },
    "minimize_results": {
      "type": "boolean",
      "description": "When true, return at most 10 results with only the essential fields. For exact matches, return only the matching result.",
      "default": false
    },
    "auto_fetch_term_info": {
      "type": "boolean",
      "description": "When true and an exact label match is found, automatically fetch and include term info in the response.",
      "default": false
    }
  },
  "required": [
    "query"
  ]
}

list_search_facets

List the type names search_terms can filter, exclude, boost or demote by, with the number of terms carrying each one. Call this instead of guessing: there are over 200 names, they are the index's own annotations rather than a curated list, and they change as data is added. Use contains to narrow (e.g. contains="lineage" for the ~120 lineage clones, contains="connectivity" to find the connectome facets). The counts tell you whether a name is broad or niche — "entity" covers everything, a single lineage covers a handful.

Parameters1

contains

string

optional

Only return type names containing this text. Matched case- and separator-insensitively, so "nervous system" finds "Nervous_system".

Raw schema

{
  "type": "object",
  "properties": {
    "contains": {
      "type": "string",
      "description": "Only return type names containing this text. Matched case- and separator-insensitively, so \"nervous system\" finds \"Nervous_system\"."
    }
  }
}

resolve_entity

Resolve an unresolved FlyBase-related query string into VFB/FlyBase IDs and metadata. Pass the raw text exactly as the user wrote it (for example "P{VT054895-GAL4.DBD}", "Hb9-GAL4", "SS04495", "MB002B", "PAM cluster", or "dpp"). Do NOT pass resolved IDs such as FBgn/FBal/FBti/FBco/FBst or VFB IDs; if you already have an ID, use the downstream tool directly. Uses tiered resolution: exact name → synonym → broad pattern match. Returns match_type (EXACT/SYNONYM/BROAD), feature ID, name, type, and synonyms. IMPORTANT: When match_type is SYNONYM or BROAD, always confirm the resolved entity with the user before proceeding to further queries. If multiple matches are returned, show a disambiguation list and ask the user to choose. This tool queries FlyBase Chado — for VFB ontology lookups (anatomical terms, neuron class IDs) use search_terms instead.

Parameters1

name

string

required

Unresolved FlyBase-related query string from the user. Pass the raw name/synonym exactly as written (e.g., "P{VT054895-GAL4.DBD}", "Hb9-GAL4", "SS04495", "MB002B", "PAM cluster", "dpp"). Do NOT pass an already resolved FlyBase or VFB ID.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Unresolved FlyBase-related query string from the user. Pass the raw name/synonym exactly as written (e.g., \"P{VT054895-GAL4.DBD}\", \"Hb9-GAL4\", \"SS04495\", \"MB002B\", \"PAM cluster\", \"dpp\"). Do NOT pass an already resolved FlyBase or VFB ID."
    }
  },
  "required": [
    "name"
  ]
}

resolve_combination

Resolve an unresolved split-GAL4 combination name or synonym into its FBco ID and component hemidrivers. Pass the raw combination text exactly as the user wrote it (for example "MB002B" or "SS04495"). Do NOT pass an FBco ID; if you already have one, use the downstream tool directly. Uses tiered resolution: exact name → synonym → broad pattern match. Returns FBco ID, combination name, matched synonym (if applicable), and component allele IDs/names. IMPORTANT: When match is via synonym, confirm the resolved combination with the user before proceeding (e.g., "Your search for 'MB002B' matched [formal name] (FBco...) via synonym. Shall I proceed?"). If multiple matches, show disambiguation list and ask user to choose.

Parameters1

name

string

required

Unresolved split-GAL4 combination name or synonym exactly as written by the user (e.g., "MB002B", "SS04495"). Do NOT pass an FBco ID here.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Unresolved split-GAL4 combination name or synonym exactly as written by the user (e.g., \"MB002B\", \"SS04495\"). Do NOT pass an FBco ID here."
    }
  },
  "required": [
    "name"
  ]
}

list_connectome_datasets

List available connectome datasets with their labels and symbols. Use the returned symbols when constructing exclude_dbs arguments for query_connectivity. Common datasets include Hemibrain (hb), FAFB (fafb), MANC, and others. Call this tool if unsure which dataset symbols are valid.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {}
}

query_connectivity

Query synaptic connectivity between Drosophila neuron classes across ALL connectome datasets simultaneously for comparative connectomics. This is NOT pre-cached — it runs live queries, so expect slow responses (up to several minutes). Set both upstream_type AND downstream_type to filter connections between two specific neuron classes (e.g., "What Tm1→T3 connections exist across all datasets?"). At least one of upstream_type or downstream_type is required. CONSTRAINTS: Only accepts neuron class terms (OWL IDs like FBbt_00003789 or labels like "transmedullary neuron Tm1") — anatomical regions or neuropils (e.g., "lobula", "medulla") are NOT accepted. NOT suitable for individual neuron-to-neuron connections — for pre-computed connections of a single individual neuron, use run_query with NeuronNeuronConnectivityQuery instead. NOT for muscle/sense organ connections. RECOMMENDED DEFAULTS: weight=5, exclude_dbs=["hb","fafb"] unless user specifies otherwise. For both-ends queries, start with weight≥50 to avoid timeouts. RESULT SIZE: a broad query is enormous (a single class at weight=5 can be over 50,000 connections), so results are ranked strongest-first and paged — you get limit rows (default 50) plus a summary computed over ALL of them: totals, per-dataset counts, distinct neuron counts, and the top class pairs. Answer from the summary and quote a handful of rows; only page with offset if the user asks for specific further rows. WORKFLOW: Confirm parameters with user before querying. Use search_terms with filter_types ["neuron","class"] to validate/canonicalize neuron type labels. If zero results, try relaxation: lower weight to 1, then remove exclude_dbs filter, then try group_by_class=true — report what worked and let user decide. group_by_class=true is usually the better first call on a broad query: it rolls the connections up over the subclass hierarchy — a row per (upstream level, downstream level) with data, up to the queried term(s) — instead of returning every neuron pair. Because a connection counts toward every ancestor pair in scope, per-row pairwise_connections and total_weight do NOT sum to the raw connection counts, and a row appears for the queried class itself as well as each subclass with data.

Parameters7

upstream_type	string	optional	Upstream (presynaptic) neuron class — OWL ID (e.g., "FBbt_00003789") or full label (e.g., "transmedullary neuron Tm1"). Must be a neuron type/class, NOT an anatomical region. Use search_terms with filter_types ["neuron","class"] to validate/canonicalize labels before querying.
downstream_type	string	optional	Downstream (postsynaptic) neuron class — OWL ID or full label. Must be a neuron type/class, NOT an anatomical region. If user asks about connectivity to a brain region, first find neuron classes in that region using search_terms, then query for those classes.
weight	number	optional	Minimum synapse count threshold (recommended default: 5). Lower to 1 if initial query returns zero results as first relaxation step.
group_by_class	boolean	optional	If true, aggregate by class rolled up over the subclass hierarchy: a row appears for the queried class AND each subclass with data (a connection counts toward every ancestor pair up to the queried term(s), so per-row pairwise_connections / total_weight do not sum to the raw counts). Returns total_weight, average_weight, percent_connected and pairwise_connections per class pair, ranked by pairwise_connections. If false (default), returns individual neuron-to-neuron rows.
exclude_dbs	array	optional	Dataset symbols to exclude (recommended default: ["hb", "fafb"] to focus on newer datasets). Pass empty array [] to include all datasets. Must be the exact `symbol` field from list_connectome_datasets — currently BANC, fw, ol, mv, hb, mc, fafb, l1em. An unrecognised symbol is silently ignored by the server rather than reported, so a dataset name ("hemibrain", "male-cns", "flywire") excludes nothing and gives no warning. Call list_connectome_datasets rather than guessing.
limit	number	optional	How many connection rows to return, strongest first (default 50). The summary always covers every connection found, not just the returned rows. Pass 0 for all rows — only do this on a query you already know is small, as broad queries return tens of thousands.
offset	number	optional	Row to start from within the strongest-first ranking (default 0). Re-running with the same limit and the next offset walks down the list.

Raw schema

{
  "type": "object",
  "properties": {
    "upstream_type": {
      "type": "string",
      "description": "Upstream (presynaptic) neuron class — OWL ID (e.g., \"FBbt_00003789\") or full label (e.g., \"transmedullary neuron Tm1\"). Must be a neuron type/class, NOT an anatomical region. Use search_terms with filter_types [\"neuron\",\"class\"] to validate/canonicalize labels before querying."
    },
    "downstream_type": {
      "type": "string",
      "description": "Downstream (postsynaptic) neuron class — OWL ID or full label. Must be a neuron type/class, NOT an anatomical region. If user asks about connectivity to a brain region, first find neuron classes in that region using search_terms, then query for those classes."
    },
    "weight": {
      "type": "number",
      "description": "Minimum synapse count threshold (recommended default: 5). Lower to 1 if initial query returns zero results as first relaxation step."
    },
    "group_by_class": {
      "type": "boolean",
      "description": "If true, aggregate by class rolled up over the subclass hierarchy: a row appears for the queried class AND each subclass with data (a connection counts toward every ancestor pair up to the queried term(s), so per-row pairwise_connections / total_weight do not sum to the raw counts). Returns total_weight, average_weight, percent_connected and pairwise_connections per class pair, ranked by pairwise_connections. If false (default), returns individual neuron-to-neuron rows."
    },
    "exclude_dbs": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Dataset symbols to exclude (recommended default: [\"hb\", \"fafb\"] to focus on newer datasets). Pass empty array [] to include all datasets. Must be the exact `symbol` field from list_connectome_datasets — currently BANC, fw, ol, mv, hb, mc, fafb, l1em. An unrecognised symbol is silently ignored by the server rather than reported, so a dataset name (\"hemibrain\", \"male-cns\", \"flywire\") excludes nothing and gives no warning. Call list_connectome_datasets rather than guessing."
    },
    "limit": {
      "type": "number",
      "description": "How many connection rows to return, strongest first (default 50). The summary always covers every connection found, not just the returned rows. Pass 0 for all rows — only do this on a query you already know is small, as broad queries return tens of thousands.",
      "default": 50
    },
    "offset": {
      "type": "number",
      "description": "Row to start from within the strongest-first ranking (default 0). Re-running with the same limit and the next offset walks down the list.",
      "default": 0
    }
  }
}

get_predicted_neurotransmitters

Get the PREDICTED neurotransmitter(s) for a Drosophila neuron class — itself or any subclass — from per-instance connectome predictions (each reconstructed neuron carries a predicted transmitter with a confidence). Use this for "what neurotransmitter does <cell type> use?" when you want the data-driven prediction and its confidence. By default results are aggregated to flat per-class rows (one per cell type × neurotransmitter) with instance counts, percent_of_class and mean_confidence; set aggregate=false for one row per individual neuron. Set split_by_dataset=true to get one row per (cell type, neurotransmitter, dataset) so you can see agreement across connectomes. The neurotransmitter is reported as a GO secretion term (nt_id/nt_label), the same id space as get_known_neurotransmitters. This is distinct from get_known_neurotransmitters, which returns the ontology-curated classification without confidence. CONSTRAINTS: neuron class terms only (FBbt id or label); use search_terms with filter_types ["neuron","class"] to canonicalize. RECOMMENDED: exclude_dbs defaults to ["hb","fafb"]; pass [] for all datasets.

Parameters5

neuron_type	string	required	Neuron class — OWL ID (e.g. "FBbt_00003797") or label (e.g. "Tm9"). Means the class and all of its subclasses.
aggregate	boolean	optional	If true (default), aggregate to flat per-class rows {cell_type_id, cell_type, nt_id, nt_label, instances, percent_of_class, mean_confidence}. If false, return one row per individual neuron {..., neuron_id, neuron_name, confidence, references, dataset}.
split_by_dataset	boolean	optional	If true (aggregate only), emit one row per (cell type, neurotransmitter, dataset) with a dataset column, so cross-connectome agreement is visible. Default false aggregates over all included datasets.
exclude_dbs	array	optional	Dataset symbols to exclude (default ["hb","fafb"]). Pass [] to include all datasets. Same symbols as query_connectivity / list_connectome_datasets.
min_confidence	number	optional	Drop predictions below this confidence (0..1). Default 0 (keep all).

Raw schema

{
  "type": "object",
  "properties": {
    "neuron_type": {
      "type": "string",
      "description": "Neuron class — OWL ID (e.g. \"FBbt_00003797\") or label (e.g. \"Tm9\"). Means the class and all of its subclasses."
    },
    "aggregate": {
      "type": "boolean",
      "description": "If true (default), aggregate to flat per-class rows {cell_type_id, cell_type, nt_id, nt_label, instances, percent_of_class, mean_confidence}. If false, return one row per individual neuron {..., neuron_id, neuron_name, confidence, references, dataset}.",
      "default": true
    },
    "split_by_dataset": {
      "type": "boolean",
      "description": "If true (aggregate only), emit one row per (cell type, neurotransmitter, dataset) with a dataset column, so cross-connectome agreement is visible. Default false aggregates over all included datasets.",
      "default": false
    },
    "exclude_dbs": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Dataset symbols to exclude (default [\"hb\",\"fafb\"]). Pass [] to include all datasets. Same symbols as query_connectivity / list_connectome_datasets."
    },
    "min_confidence": {
      "type": "number",
      "description": "Drop predictions below this confidence (0..1). Default 0 (keep all).",
      "default": 0
    }
  },
  "required": [
    "neuron_type"
  ]
}

get_known_neurotransmitters

Get the KNOWN (curated) neurotransmitter(s) for a Drosophila neuron class and its subclasses, from the ontology's classification rather than per-instance predictions — so there is no confidence. Use this for "what neurotransmitter is <cell type> known to use?" when you want the curated/established answer. Returns one row per (cell type, neurotransmitter): {cell_type_id, cell_type, nt_id, nt_label}, where the neurotransmitter is a GO secretion term (same id space as get_predicted_neurotransmitters). Empty when the ontology asserts none — in that case try get_predicted_neurotransmitters for the data-driven prediction. CONSTRAINTS: neuron class terms only (FBbt id or label); use search_terms with filter_types ["neuron","class"] to canonicalize.

Parameters1

neuron_type

string

required

Neuron class — OWL ID (e.g. "FBbt_00003797") or label (e.g. "Tm9"). Means the class and all of its subclasses.

Raw schema

{
  "type": "object",
  "properties": {
    "neuron_type": {
      "type": "string",
      "description": "Neuron class — OWL ID (e.g. \"FBbt_00003797\") or label (e.g. \"Tm9\"). Means the class and all of its subclasses."
    }
  },
  "required": [
    "neuron_type"
  ]
}

get_hierarchy

Build a hierarchy tree for a VFB term, showing ancestors (parents) and/or descendants (children). Use relationship "part_of" for brain region structure (e.g. "what are the parts of the mushroom body?") and "subclass_of" for cell type hierarchies (e.g. "what types of Kenyon cell are there?"). Descendants are returned as a nested tree for both relationship types. Ancestors are returned as a nested chain, filtered to nervous system terms for part_of. Start with max_depth=1 for direct parents/children, and offer to go deeper if the user wants more detail.

Parameters4

id	string	required	VFB term ID (e.g. FBbt_00005801 for mushroom body, FBbt_00003686 for Kenyon cell)
relationship	string	required	Type of hierarchy: "part_of" for brain region structure, "subclass_of" for cell type taxonomies
direction	string	optional	Which direction to explore (default: "both")
max_depth	number	optional	Number of levels to expand. 1 = direct children/parents only. Higher values go deeper. -1 = full tree (use with caution on broad terms). Default: 1.

Raw schema

{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "description": "VFB term ID (e.g. FBbt_00005801 for mushroom body, FBbt_00003686 for Kenyon cell)"
    },
    "relationship": {
      "type": "string",
      "enum": [
        "part_of",
        "subclass_of"
      ],
      "description": "Type of hierarchy: \"part_of\" for brain region structure, \"subclass_of\" for cell type taxonomies"
    },
    "direction": {
      "type": "string",
      "enum": [
        "descendants",
        "ancestors",
        "both"
      ],
      "description": "Which direction to explore (default: \"both\")",
      "default": "both"
    },
    "max_depth": {
      "type": "number",
      "description": "Number of levels to expand. 1 = direct children/parents only. Higher values go deeper. -1 = full tree (use with caution on broad terms). Default: 1.",
      "default": 1
    }
  },
  "required": [
    "id",
    "relationship"
  ]
}

README.md17 KBView on GitHub

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://vfb3-mcp.virtualflybrain.org — no installation, no API key, no account.

bash

claude mcp add --transport http virtual-fly-brain https://vfb3-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://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": {
      "type": "http",
      "url": "https://vfb3-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:

json

{
  "mcpServers": {
    "virtual-fly-brain": {
      "type": "http",
      "url": "https://vfb3-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://vfb3-mcp.virtualflybrain.org
Give it a name like "Virtual Fly Brain"

Alternative JSON configuration (in mcp.json):

json

{
  "servers": {
    "virtual-fly-brain": {
      "type": "http",
      "url": "https://vfb3-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://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": {
      "type": "http",
      "url": "https://vfb3-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?"

🛠️ 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 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

🛠️ Local Installation

Prerequisites

Node.js 18 or higher
npm or yarn

Step-by-Step Installation

Clone the repository:

bash

git clone https://github.com/VirtualFlyBrain/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")
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. 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)

🧠 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

Tools (11)

get_term_inforun_querysearch_termslist_search_facetsresolve_entityresolve_combinationlist_connectome_datasetsquery_connectivity

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://vfb3-mcp.virtualflybrain.org

Add to VS Code Add to Cursor

claude_desktop_config.json

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.

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

get_term_info

run_query

search_terms

list_search_facets

resolve_entity

resolve_combination

list_connectome_datasets

query_connectivity

get_predicted_neurotransmitters

get_known_neurotransmitters

get_hierarchy

VFB3-MCP Server

🚀 Quick Start

Use the Live Service (Recommended)

Claude Desktop Setup

Claude Code Setup

GitHub Copilot Setup

Visual Studio Code (with MCP Extension)

Other MCP Clients

Gemini Setup

Testing the Connection

Example Workflow

🛠️ Available Tools

🛠️ Local Installation

Prerequisites

Step-by-Step Installation

Platform-Specific Setup

Claude Desktop (Local Development)

Claude Code

Visual Studio Code

GitHub Copilot

Docker Installation

Available Tools

get_term_info

run_query

search_terms

list_search_facets

query_connectivity

get_predicted_neurotransmitters

get_known_neurotransmitters

🧠 About VirtualFlyBrain

📖 Documentation

📄 License

Install

Remote endpoint

Related servers