# FishBase MCP

> FishBase connects your AI agent to global marine biology databases, giving you access to the world's largest collection of fish species data and documentation. Query common names for thousands of species, track database versions over time, or check the API health status—all from one place. It handles both FishBase and SeaLifeBase schemas so you don't have to worry about which source you need.

## Overview
- **Category:** databases
- **Price:** Free
- **Tags:** ichthyology, marine-biology, fish-database, species-data, sealifebase

## Description

This connection lets your AI agent pull deep scientific data directly from two major global fish databases: FishBase and SeaLifeBase. Instead of opening multiple web tabs or running complex database queries, you can simply ask your agent for information using natural language. You can get lists of common species names across different regions, verify which version of the data is most current, or pull the technical documentation required to understand a specific table's structure.

It’s built to handle both primary databases through one interface. If you use Vinkius as your catalog, your agent connects once and gains immediate access to all this ichthyological knowledge. It means researchers can quickly verify species records or data scientists can map out schemas without ever leaving their workflow.

## Tools

### list_comnames
Accesses common names data for fishes, supporting filtering and pagination across species.

### get_docs_by_table
Pulls specific technical documentation and schema details for a single, named database table.

### get_docs
Retrieves general metadata about the entire FishBase API documentation set.

### get_heartbeat
Checks the real-time operational status of the FishBase API to confirm connectivity.

### get_versions
Lists all available database versions, allowing you to track historical data records for specific dates.

## Prompt Examples

**Prompt:** 
```
Check if the FishBase API is currently online.
```

**Response:** 
```
I've checked the FishBase API status using `get_heartbeat`. The API is up and running, returning a successful heartbeat signal.
```

**Prompt:** 
```
List the common names for 'Gadus morhua' in FishBase.
```

**Response:** 
```
I've retrieved the common names for *Gadus morhua* (Atlantic cod) using `list_comnames`. Results include various regional names such as 'Cod', 'Morue', and 'Bacalao'.
```

**Prompt:** 
```
Show me the documentation for the 'species' table in SeaLifeBase.
```

**Response:** 
```
Using `get_docs_by_table` with `use_sealifebase` set to true, I've fetched the documentation for the 'species' table. This table contains primary taxonomic information and species-level metadata.
```

## Capabilities

### List common names for fish
It searches the databases and lists regional, common names associated with a given scientific species name.

### Check API connectivity status
It runs a simple check to confirm that the entire database connection is currently online and operational.

### Retrieve available data versions
It lists all historical or current versions of the underlying FishBase/SeaLifeBase databases for tracking purposes.

### Get technical table documentation
It pulls metadata, explaining exactly what fields and columns exist within a specific database table.

## Use Cases

### Identifying a new species name for a paper
A marine biologist needs common names for *Gadus morhua*. Instead of visiting multiple sites, they ask their agent. The agent uses `list_comnames` and returns 'Cod', 'Morue', and 'Bacalao' immediately, saving research time.

### Comparing schema across two projects
A data scientist needs to know the structure of tables in both FishBase and SeaLifeBase. They use `get_docs_by_table` twice, getting side-by-side documentation for 'species' metadata from both systems.

### Debugging a historical dataset discrepancy
A researcher suspects data integrity issues in an old report. They first use `get_versions` to confirm the exact date range of the available records, then check the status with `get_heartbeat` before proceeding.

### Building a reliable scientific application
A developer building a web app needs constant uptime assurance. They integrate `get_heartbeat` into their system's startup routine, ensuring the AI agent knows instantly if the primary data source is offline.

## Benefits

- Stop guessing which data source to use. The connection handles both FishBase and SeaLifeBase databases, so you only need one query regardless of the underlying schema.
- Verify species names quickly without juggling multiple sites. Use `list_comnames` to fetch common regional names for any given scientific identifier.
- Understand your dataset fully before analyzing it. Pull specific documentation using `get_docs_by_table` to map out a table's exact columns and metadata.
- Track data history with confidence. The `get_versions` tool lets you know exactly which version of the database you’re working with, crucial for longitudinal studies.
- Build reliable workflows that check status automatically. Use `get_heartbeat` to ensure your agent doesn't fail due to an unexpected API outage.

## How It Works

The bottom line is you talk to your agent, and it handles all the database connections and data retrieval steps automatically.

1. Subscribe to this MCP on Vinkius. You'll need your FishBase API Key if the provider requires it.
2. Your AI agent connects and confirms the connection status using one of the specialized tools.
3. You then prompt your agent with a query, like listing common names or asking for documentation on a specific table.

## Frequently Asked Questions

**How do I check if the FishBase API is online using get_heartbeat?**
Run `get_heartbeat`. It immediately confirms the API's operational status. A successful heartbeat signal means your agent can proceed with data queries.

**What is the difference between get_docs and get_docs_by_table?**
Use `get_docs` for overall metadata about the entire FishBase API structure. Use `get_docs_by_table` when you want specific, field-level documentation for one single database table.

**Can list_comnames find common names for a species?**
Yes, `list_comnames` is designed to access and list regional common names associated with a scientific species name. It supports filtering and pagination too.

**Which tool should I use if I want to know the data version?**
Use `get_versions`. This tool lists all available database versions, giving you control over which historical dataset your analysis references.

**When using list_comnames, how do I ensure I'm pulling data from a specific source like SeaLifeBase?**
The query system handles switching between FishBase and SeaLifeBase sources. You don't need separate calls; you just specify your desired database context in the request parameters for `list_comnames`. This lets you verify species common names without needing to know which underlying source holds the most accurate record.

**If I run list_comnames and get thousands of results, how do I handle filtering or pagination?**
You must use the provided parameters for chunking large result sets. The tool supports explicit pagination controls, letting you request data in manageable batches. You can also apply specific field filters to narrow down your common names list efficiently.

**When I'm building a new analysis and need to understand the whole system structure, should I use get_docs or get_docs_by_table?**
Use `get_docs` first if you want an overview of the entire API's metadata. If you know exactly which table you need—like 'species'—you must run `get_docs_by_table`. The former provides context; the latter delivers specific schema details for one place.

**What should I do if my initial attempt with any tool fails, and I suspect it’s a rate limit issue?**
Check the API status first using `get_heartbeat`. If that passes but subsequent calls fail, you've likely hit a usage cap. In that case, wait for your key refresh cycle or check documentation regarding bulk request limits.

**Can I switch between FishBase and SeaLifeBase data?**
Yes. Most tools include a `use_sealifebase` parameter. Set it to `true` to query the SeaLifeBase database instead of the default FishBase.

**How do I find the common names for a specific fish species?**
Use the `list_comnames` tool and provide the species name in the `species` parameter. You can also limit the results or filter specific fields.

**Where can I find documentation for the database tables?**
You can use `get_docs` for general metadata or `get_docs_by_table` to get detailed documentation for a specific table name.