VFB3-MCP
OfficialREADME.md
# 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](https://github.com/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.)
```bash
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
1. **Open Claude Desktop** and go to Settings
2. **Navigate to the MCP section**
3. **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):
```json
{
"mcpServers": {
"virtual-fly-brain": {
"type": "http",
"url": "https://mcp.virtualflybrain.org",
"tools": ["*"]
}
}
}
```
#### Claude Code Setup
1. **Locate your Claude configuration file**:
- **macOS/Linux**: `~/.claude.json`
- **Windows**: `%USERPROFILE%\.claude.json`
2. **Add the VFB3-MCP server** to your configuration:
```json
{
"mcpServers": {
"virtual-fly-brain": {
"type": "http",
"url": "https://mcp.virtualflybrain.org",
"tools": ["*"]
}
}
}
```
3. **Restart Claude Code** for changes to take effect
#### GitHub Copilot Setup
1. **Open VS Code** with GitHub Copilot installed
2. **Open Settings** (`Ctrl/Cmd + ,`)
3. **Search for "MCP"** in the settings search
4. **Find the MCP Servers setting**
5. **Add the server URL**: `https://mcp.virtualflybrain.org`
6. **Give it a name** like "Virtual Fly Brain"
**Alternative JSON configuration** (in `mcp.json`):
```json
{
"servers": {
"virtual-fly-brain": {
"type": "http",
"url": "https://mcp.virtualflybrain.org"
}
}
}
```
#### Visual Studio Code (with MCP Extension)
1. **Install the MCP extension** for VS Code from the marketplace
2. **Open the Command Palette** (`Ctrl/Cmd + Shift + P`)
3. **Type "MCP: Add server"** and select it
4. **Choose "HTTP"** as the server type
5. **Enter the server details**:
- **Name**: `virtual-fly-brain`
- **URL**: `https://mcp.virtualflybrain.org`
6. **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://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](examples.md)**.
### Example Workflow
1. **Search for a term**: "Search for neurons in the optic lobe"
2. **Get detailed info**: "Get information about VFB_00101567"
3. **Run specific queries**: "Show connectivity for VFB_00101567"
4. **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
- `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](#-tool-reference) below.
## π οΈ Local Installation
### Prerequisites
- Node.js 18 or higher
- npm or yarn
### Step-by-Step Installation
1. **Clone the repository**:
```bash
git clone https://github.com/VirtualFlyBrain/VFB3-MCP.git
cd VFB3-MCP
```
2. **Install dependencies**:
```bash
npm install
```
3. **Build the project**:
```bash
npm run build
```
4. **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
1. Install the MCP extension for VS Code
2. Press `Cmd + Shift + P` (macOS) or `Ctrl + Shift + P` (Windows/Linux)
3. Select **MCP: Add serverβ¦**
4. Choose **Command** type
5. 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:
```
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
```
## π 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 (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
- **[LLM Guidance](LLM_GUIDANCE.md)**: Guide for AI assistants on using this MCP effectively
- **[Examples](examples.md)**: Usage examples and integration guides
- **[Technical Documentation](TECHNICAL.md)**: Infrastructure, deployment, and development details
## π License
MIT
This server cannot be deployed
Maintenance
ActivityActive
ResponsivenessLimited data