{
  "markdown": "# VFB3-MCP Server\n\nA 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.\n\n**Canonical repository:** [VirtualFlyBrain/VFB3-MCP](https://github.com/VirtualFlyBrain/VFB3-MCP) (this one) — maintained by the Virtual Fly Brain team.\n**Hosted service:** `https://vfb3-mcp.virtualflybrain.org` — no installation, no API key, no account.\n\n```bash\nclaude mcp add --transport http virtual-fly-brain https://vfb3-mcp.virtualflybrain.org\n```\n\nThe earlier copy at `Robbie1977/VFB3-MCP` is archived at v1.3.0 and is not maintained; use this repository and the URL above.\n\nThis 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.\n\n## 🚀 Quick Start\n\n### Use the Live Service (Recommended)\n\nThe 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.\n\n#### Claude Desktop Setup\n\n1. **Open Claude Desktop** and go to Settings\n2. **Navigate to the MCP section**\n3. **Add a new MCP server** with these settings:\n   - **Server Name**: `virtual-fly-brain` (or any name you prefer)\n   - **Type**: HTTP\n   - **Server URL**: `https://vfb3-mcp.virtualflybrain.org`\n\n**Configuration JSON** (alternative method):\n```json\n{\n  \"mcpServers\": {\n    \"virtual-fly-brain\": {\n      \"type\": \"http\",\n      \"url\": \"https://vfb3-mcp.virtualflybrain.org\",\n      \"tools\": [\"*\"]\n    }\n  }\n}\n```\n\n#### Claude Code Setup\n\n1. **Locate your Claude configuration file**:\n   - **macOS/Linux**: `~/.claude.json`\n   - **Windows**: `%USERPROFILE%\\.claude.json`\n\n2. **Add the VFB3-MCP server** to your configuration:\n```json\n{\n  \"mcpServers\": {\n    \"virtual-fly-brain\": {\n      \"type\": \"http\",\n      \"url\": \"https://vfb3-mcp.virtualflybrain.org\",\n      \"tools\": [\"*\"]\n    }\n  }\n}\n```\n\n3. **Restart Claude Code** for changes to take effect\n\n#### GitHub Copilot Setup\n\n1. **Open VS Code** with GitHub Copilot installed\n2. **Open Settings** (`Ctrl/Cmd + ,`)\n3. **Search for \"MCP\"** in the settings search\n4. **Find the MCP Servers setting**\n5. **Add the server URL**: `https://vfb3-mcp.virtualflybrain.org`\n6. **Give it a name** like \"Virtual Fly Brain\"\n\n**Alternative JSON configuration** (in `mcp.json`):\n```json\n{\n  \"servers\": {\n    \"virtual-fly-brain\": {\n      \"type\": \"http\",\n      \"url\": \"https://vfb3-mcp.virtualflybrain.org\"\n    }\n  }\n}\n```\n\n#### Visual Studio Code (with MCP Extension)\n\n1. **Install the MCP extension** for VS Code from the marketplace\n2. **Open the Command Palette** (`Ctrl/Cmd + Shift + P`)\n3. **Type \"MCP: Add server\"** and select it\n4. **Choose \"HTTP\"** as the server type\n5. **Enter the server details**:\n   - **Name**: `virtual-fly-brain`\n   - **URL**: `https://vfb3-mcp.virtualflybrain.org`\n6. **Save and restart** VS Code if prompted\n\n#### Other MCP Clients\n\nFor any MCP-compatible client that supports HTTP servers:\n\n```json\n{\n  \"mcpServers\": {\n    \"virtual-fly-brain\": {\n      \"type\": \"http\",\n      \"url\": \"https://vfb3-mcp.virtualflybrain.org\",\n      \"tools\": [\"*\"]\n    }\n  }\n}\n```\n\n#### Gemini Setup\n\nTo 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.\n\n**Note**: Direct Gemini web interface integration with MCP is not currently supported. Developer tools are needed to connect the two.\n\n**Option 1: Using Python**\n\nFor application development, use the `mcp` and `google-genai` libraries to connect.\n\nSetup: `pip install google-genai mcp`\n\nImplementation: 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.\n\n#### Testing the Connection\n\nOnce configured, you can test that VFB3-MCP is working by asking your AI assistant questions like:\n\n**Basic Queries:**\n- \"Get information about the neuron VFB_jrcv0i43\"\n- \"Search for terms related to medulla in the fly brain\"\n- \"What neurons are in the antennal lobe?\"\n\n**Advanced Queries:**\n- \"Find all neurons that connect to the mushroom body\"\n- \"Show me expression patterns for gene repo\"\n- \"What brain regions are involved in olfactory processing?\"\n- \"Run a connectivity analysis for neuron VFB_00101567\"\n\n**Search Examples:**\n- \"Search for adult neurons in the visual system\"\n- \"Find genes expressed in the central complex\"\n- \"Show me all templates available in VFB\"\n\nIf you see responses with VirtualFlyBrain data, including neuron names, brain regions, gene expressions, or connectivity information, the setup is successful!\n\nFor more detailed usage examples and API calls, see **[examples.md](examples.md)**.\n\n### Example Workflow\n\n1. **Search for a term**: \"Search for neurons in the optic lobe\"\n2. **Get detailed info**: \"Get information about VFB_00101567\"\n3. **Run specific queries**: \"Show connectivity for VFB_00101567\"\n4. **Explore relationships**: \"What neurons synapse in the mushroom body?\"\n\n## 🛠️ Available Tools\n\nThe MCP server exposes the following tools (available to assistants like Claude and Copilot):\n\n- `get_term_info` — Get detailed metadata for a VFB ID\n- `run_query` — Run a precomputed analysis query for a VFB ID (see the `Queries` field from `get_term_info`)\n- `search_terms` — Search VFB entities by text with filtering / boosting options. This is the same search virtualflybrain.org itself runs\n- `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\n- `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)\n- `resolve_combination` — Resolve an unresolved split-GAL4 combination name or synonym into its component IDs\n- `list_connectome_datasets` — List available connectome datasets (e.g., Hemibrain, FAFB)\n- `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\n- `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\n\n## 🛠️ Local Installation\n\n### Prerequisites\n\n- Node.js 18 or higher\n- npm or yarn\n\n### Step-by-Step Installation\n\n1. **Clone the repository**:\n   ```bash\n   git clone https://github.com/VirtualFlyBrain/VFB3-MCP.git\n   cd VFB3-MCP\n   ```\n\n2. **Install dependencies**:\n   ```bash\n   npm install\n   ```\n\n3. **Build the project**:\n   ```bash\n   npm run build\n   ```\n\n4. **Start the server**:\n   ```bash\n   npm start\n   ```\n\n### Platform-Specific Setup\n\n#### Claude Desktop (Local Development)\n\nFor local development with Claude Desktop, add this to your MCP configuration:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"vfb3-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/VFB3-MCP/dist/index.js\"]\n    }\n  }\n}\n```\n\n#### Claude Code\n\nAdd to your `claude.json` file:\n```json\n{\n  \"mcpServers\": {\n    \"vfb3-mcp\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/VFB3-MCP/dist/index.js\"]\n    }\n  }\n}\n```\n\n#### Visual Studio Code\n\n1. Install the MCP extension for VS Code\n2. Press `Cmd + Shift + P` (macOS) or `Ctrl + Shift + P` (Windows/Linux)\n3. Select **MCP: Add server…**\n4. Choose **Command** type\n5. Enter:\n   - **Name**: `vfb3-mcp`\n   - **Command**: `node`\n   - **Arguments**: `/absolute/path/to/VFB3-MCP/dist/index.js`\n\n#### GitHub Copilot\n\nConfigure the MCP server URL in your Copilot settings to point to your local server:\n```\nhttp://localhost:3000\n```\n\nFor HTTP mode testing:\n```bash\nMCP_MODE=http PORT=3000 node dist/index.js\n```\n\n### Docker Installation\n\n**Using Docker Compose** (Recommended):\n```bash\ndocker-compose up --build\n```\n\n**Manual Docker Build**:\n```bash\n# Build the image\ndocker build -t vfb3-mcp .\n\n# Run the container\ndocker run -p 3000:3000 vfb3-mcp\n```\n\n**Pull Pre-built Image**:\n```bash\ndocker pull virtualflybrain/vfb3-mcp:latest\ndocker run -p 3000:3000 virtualflybrain/vfb3-mcp:latest\n```\n\n##  Available Tools\n\n### get_term_info\nRetrieve detailed information about VFB terms using their IDs.\n\n**Parameters:**\n- `id` (string): VFB ID (e.g., \"VFB_jrcv0i43\")\n- `force_refresh` (boolean, optional): Bypass the response cache and recompute (see `run_query` below for the cost and the whitelisting caveat)\n\n### run_query\nExecute predefined queries on VFB data.\n\n**Parameters:**\n- `id` (string or array): One or more VFB IDs (e.g., \"VFB_00101567\")\n- `query_type` (string): Query type from the entity's `Queries` array (e.g., \"PaintedDomains\")\n- `queries` (array, optional): `{id, query_type}` pairs for mixed batch queries\n- `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)\n- `offset` (number, optional): Row offset for paging (default 0); re-run with `offset += limit` for the next page\n- `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)\n- `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.\n\nThe 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.\n\nFlyBase stocks and split-GAL4 combination publications are run_query query_types too: `FindStocks` and `FindComboPublications`.\n\n### search_terms\nSearch 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.\n\n**Parameters:**\n- `query` (string): Search query (e.g., \"medulla\")\n- `filter_types` (array, optional): Keep only results matching ALL of these facets_annotation types (AND logic)\n- `exclude_types` (array, optional): Drop results matching ANY of these facets_annotation types (OR logic)\n- `boost_types` (array, optional): Lift results matching these types up the ranking without excluding others\n- `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`\n- `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\n- `start` (number, optional): Page start index (default 0)\n- `rows` (number, optional): Rows to return (default 150, max 1000)\n- `minimize_results` (boolean, optional): Return only the top 10 with reduced fields, for a first look (default false)\n- `auto_fetch_term_info` (boolean, optional): When the query matches one term's name exactly, also fetch that term's info (default false)\n\nType 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.\n\n### list_search_facets\nList the valid `facets_annotation` type names for the four type filters above, read from the live vocabulary.\n\n**Parameters:**\n- `contains` (string, optional): Case- and separator-insensitive substring filter (e.g., \"neuron\", \"nervous system\")\n\nIf 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.\n\n### query_connectivity\nQuery 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.\n\n**Parameters:**\n- `upstream_type` / `downstream_type` (string, optional): Neuron class OWL ID or label. Anatomical regions are not accepted\n- `weight` (number, optional): Minimum synapse count (recommended 5; use ≥50 when both ends are specified)\n- `group_by_class` (boolean, optional): Aggregate to class pairs instead of neuron pairs — usually the better first call on a broad query\n- `exclude_dbs` (array, optional): Dataset symbols to exclude (recommended `[\"hb\",\"fafb\"]`); see `list_connectome_datasets`\n- `limit` (number, optional): Rows to return, strongest first (default 50; `0` for all)\n- `offset` (number, optional): Row to start from within the ranking (default 0)\n\n## 🧠 About VirtualFlyBrain\n\nVirtualFlyBrain (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.\n\n## 📖 Documentation\n\n- **[LLM Guidance](LLM_GUIDANCE.md)**: Guide for AI assistants on using this MCP effectively\n- **[Examples](examples.md)**: Usage examples and integration guides\n- **[Technical Documentation](TECHNICAL.md)**: Infrastructure, deployment, and development details\n\n## 📄 License\n\nMIT\n",
  "bytes": 14528,
  "sha": "a65baf03763ac1c541f9dc0fee2738d54dd59dfea16fa0c5774a038cc4133786",
  "repo_slug": "virtualflybrain/vfb3-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_org_virtualflybrain_vfb3_mcp_d1cdcc18/readme"
}