brapi-mcp-server

<div align="center">
  <h1>@cyanheads/brapi-mcp-server</h1>
  <p><b>A collaborative BrAPI v2.1 workspace for multi-agent research via MCP. Search studies, germplasm, genotypes, and more across Breedbase, T3, Sweetpotatobase, and any BrAPI v2-compliant server.</b>
  <div>25 Tools • 6 Resources • 2 Prompts</div>
  </p>
</div>

<div align="center">

[![Version](https://img.shields.io/badge/Version-0.9.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/cyanheads/brapi-mcp-server/pkgs/container/brapi-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.3.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/brapi-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/brapi-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.3-blueviolet.svg?style=flat-square)](https://bun.sh/) [![Status](https://img.shields.io/badge/Status-Beta-yellow.svg?style=flat-square)](./CHANGELOG.md)

</div>

<div align="center">

[![Install in Claude Desktop](https://img.shields.io/badge/Install_in-Claude_Desktop-D97757?style=for-the-badge&logo=anthropic&logoColor=white)](https://github.com/cyanheads/brapi-mcp-server/releases/latest/download/brapi-mcp-server.mcpb) [![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=brapi-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvYnJhcGktbWNwLXNlcnZlciJdfQ==) [![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_Server-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22brapi-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads/brapi-mcp-server%22%5D%7D)

[![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-67E8F9?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)

</div>

<div align="center">

**Public Hosted Server:** [https://brapi.caseyjhand.com/mcp](https://brapi.caseyjhand.com/mcp)

</div>

---

## Overview

Plant-breeding data from any BrAPI (Breeding API) v2 server — Breedbase instances like Cassavabase and Sweetpotatobase, the Triticeae Toolbox (T3), and more, several at once. Search studies, germplasm, observations, and genotypes, walk pedigrees, and build phenotype and genotype matrices, with large results queryable in SQL.

### Tools

| Tool | Description |
|:---|:---|
| `brapi_connect` | Authenticate to a BrAPI v2 server, register it under an alias, and return the orientation envelope |
| `brapi_server_info` | Return the orientation envelope for an alias, optionally refreshing capabilities |
| `brapi_describe_filters` | List valid filter names for an endpoint, for use in any finder's `extraFilters` |
| `brapi_find_studies` | Find studies by crop, trial type, season, location, or program |
| `brapi_get_study` | Fetch a study with program, trial, and location resolved, plus companion counts |
| `brapi_find_germplasm` | Find germplasm by name, synonym, accession, PUI, crop, or free text |
| `brapi_get_germplasm` | Fetch a germplasm with attributes, direct parents, and companion counts |
| `brapi_walk_pedigree` | Walk ancestry or descendancy as a deduplicated DAG with cycle detection |
| `brapi_find_variables` | Find observation variables by name, trait class, or ontology term, with free-text ranking |
| `brapi_find_observations` | Pull observation records by study, germplasm, variable, season, or unit |
| `brapi_find_images` | Find image metadata by unit, observation, study, ontology term, or MIME type |
| `brapi_get_image` | Fetch up to 5 images inline as image content blocks |
| `brapi_find_locations` | Find research stations by country, type, abbreviation, or bounding box |
| `brapi_find_variants` | Find variants by variant set, reference, or genomic region |
| `brapi_find_genotype_calls` | Pull genotype calls through async search, bounded by a deployment pull ceiling |
| `brapi_dataframe_describe` | List dataframes, or describe one with columns, row count, and provenance |
| `brapi_dataframe_query` | Run read-only SQL across dataframes |
| `brapi_dataframe_drop` | _Opt-in._ Drop a dataframe by name |
| `brapi_dataframe_export` | _Opt-in, stdio-only._ Export a dataframe to disk as CSV, Parquet, or JSON |
| `brapi_build_phenotype_matrix` | Build a germplasm × trait matrix from one or more studies as a dataframe |
| `brapi_germplasm_performance` | Per-variable aggregates (n, mean, median, sd, min, max) for one germplasm across its studies |
| `brapi_export_genotype_matrix` | Pivot a variant set's calls into a germplasm × variant matrix, with VCF-lite or PLINK text |
| `brapi_submit_observations` | _Opt-in._ Two-phase observation write: `preview` validates, `apply` confirms and writes |
| `brapi_raw_get` | Passthrough to any `GET /{path}` endpoint no curated tool covers |
| `brapi_raw_search` | Passthrough to any `POST /search/{noun}` endpoint, with async polling handled |

### Resources

| Resource | Description |
|:---|:---|
| `brapi://server/info` | Orientation envelope for the default connection |
| `brapi://calls` | Raw capability profile (`/serverinfo` + `/calls`) for the default connection |
| `brapi://study/{studyDbId}` | One study with program, trial, and location resolved |
| `brapi://germplasm/{germplasmDbId}` | One germplasm with attributes and parents |
| `brapi://filters/{endpoint}` | Filter catalog for one endpoint |
| `brapi://variable/{observationVariableDbId}` | One observation variable (trait, scale, method, ontology) |

Every resource reads the `default` connection and mirrors a tool; tool-only clients and multi-server workflows use the tools.

### Prompts

| Prompt | Description |
|:---|:---|
| `brapi_eda_study` | Exploratory-data-analysis playbook for one study, ending in a structured report |
| `brapi_meta_analysis` | Cross-study meta-analysis playbook for a germplasm × trait combination |

## Capability reference

### `brapi_connect` <sub>tool</sub>

- `baseUrl` and `auth` are optional: omitted values come from `BRAPI_<ALIAS>_*` env vars, the built-in aliases, then `BRAPI_DEFAULT_*` (see [Per-alias credentials](#per-alias-credentials)); `alias` (default `default`, pattern `^[a-zA-Z0-9_-]+$`) keeps several servers registered at once; `auth.mode` is `none`, `bearer`, `api_key`, `sgn` (Breedbase `/token` exchange), or `oauth2` (client credentials)
- Returns the orientation envelope: `server` identity, `auth` summary, `capabilities` (`supported`, `notableGaps`), active `dialect`, `content` counts, `attribution` for built-in servers, and `nextToolSuggestions` naming the entry-point finders this server can serve
- Typed errors: `auth_session_required`, `auth_base_url_mismatch`, `alias_base_url_unset`, `alias_base_url_invalid`, `private_address_blocked`, `auth_token_exchange_failed`, `auth_no_access_token`, `upstream_unauthorized`, `upstream_forbidden`, `capability_discovery_unavailable` (retryable); a failed connect leaves any earlier registration under the alias intact
- Optional for an alias the server has a URL for (`default` when `BRAPI_DEFAULT_BASE_URL` is set, a built-in, or a `BRAPI_<ALIAS>_BASE_URL` alias): any other tool or resource connects it on first use, as `brapi_connect` with no `baseUrl` or `auth` would, and concurrent first calls share one connect. An alias with no URL of its own still fails `unknown_alias`, even with `BRAPI_DEFAULT_*` set, so a mistyped alias never reaches the default server. Those tools and resources declare the connect failures they can hit (the token, discovery, auth-wall, `alias_base_url_invalid`, and `private_address_blocked` errors above), each with a recovery hint

---

### `brapi_server_info` <sub>tool</sub>

- `alias` optional; `forceRefresh` (default `false`) refetches the capability profile instead of reading the cache
- Returns the same orientation envelope as `brapi_connect`

---

### `brapi_describe_filters` <sub>tool</sub>

- `endpoint` is one of `studies`, `germplasm`, `observations`, `variables`, `images`, `variants`, `locations`; `unknown_endpoint` carries `availableEndpoints`
- Each filter has `name`, `type`, `description`, and `example`; the catalog follows the v2.1 spec, and individual servers may honor a subset

---

### `brapi_find_studies` <sub>tool</sub>

- Filters: `crop`, `trialTypes`, `seasons`, `locations`, `programs`, `trials`, `studyNames`, `active`; on SGN servers (CassavaBase, Breedbase, Sweetpotatobase), which ignore the location filter on `/studies`, `locations` is applied client-side over the scanned studies, and `totalCount` is the matched count
- `distributions` over `programName`, `studyType`, `seasons`, `locationName`, `commonCropName`

---

### `brapi_get_study` <sub>tool</sub>

- `studyDbId` required; resolves `program`, `trial`, and `location` inline; `study_not_found` when the upstream has no such study
- Companion counts `observationCount`, `observationUnitCount`, `variableCount`; a count the server can't scope to the study is omitted with a warning, never reported as the server-wide total

---

### `brapi_find_germplasm` <sub>tool</sub>

- Filters: `names`, `germplasmDbIds`, `germplasmPUIs`, `accessionNumbers`, `crops`, `synonyms`, `collections`, `genus`, `species`; `text` is a client-side substring match on name, PUI, accession, display name, and synonyms that drops non-matching rows; it scans every upstream row when the set fits one dataframe walk (50,000 rows at the default page size), and above that a first-page miss stops the scan, so pair it with a server-sid