This server exposes fisheries and marine data discovery plus targeted retrieval through an AI/MCP client.
List connected data sources and their current coverage.
Search FishStat aquatic species or species groups by name/code.
Retrieve annual FishStat production tonnes by country/area for a species/group, filtering all, capture, or aquaculture, with optional exact ASFIS species code and CSV export.
Fetch weekly mean adult female salmon lice for a Norwegian aquaculture locality and year via BarentsWatch.
Search the live Copernicus Marine catalogue for ocean variables and dataset IDs.
Describe Copernicus Marine datasets: variables, units, coverage, version, and product DOI.
Download bounded Copernicus Marine subsets by dataset, variable, bounding box, and start/end dates as NetCDF, Zarr, or CSV with provenance.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@fisheries-data Which countries produced oysters in 2024 and how many tonnes each? Include aquaculture and capture."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A local Model Context Protocol server that connects your AI client to fisheries and marine data sources. Ask a research question, find relevant datasets, and download files with their units, structure and source information. Statistical analysis and joining datasets remain part of your research workflow.
How to install · Update Codex (Windows) · Data coverage · FAQ · Technical reference
Source | What you can retrieve | Access |
FAO FishStat | Capture and aquaculture production quantities; aquaculture production values | No account required |
BarentsWatch | Norwegian aquaculture sites, lice, temperature, treatments, diseases, escapes, permitted capacity and site details | BarentsWatch API client ID and secret |
Copernicus Marine | Ocean datasets selected by variable, geographic area and dates | Copernicus Marine account for downloads |
UN Comtrade | Annual or monthly goods trade by country, partner, HS product and flow | Free API subscription key required for downloads |
The catalogue also describes collections whose downloads are not implemented. These are marked catalogue_only; entries with download tools are marked downloadable. Availability still depends on the requested species, place, period and your access.
Related MCP server: ERDDAP MCP Server
These steps use Windows PowerShell, with Codex or Claude Code already installed and signed in. You do not need a GitHub account or the FishStat desktop application.
If you do not have Python 3.11 or newer, run:
winget install --id Python.Python.3.13 -eClose and reopen PowerShell. If WinGet is unavailable, use the Python Windows installer.
Without Git: select Code → Download ZIP on the repository page, extract the ZIP, and open PowerShell in the extracted folder containing install.py.
With Git:
git clone https://github.com/adamsconchallos/fisheries-data-mcp.git
cd fisheries-data-mcpFrom that folder, run:
py -3 install.pyThe installer prepares the server, creates .env and mcp-config.json, and prints the absolute executable path. Existing credentials are preserved.
Codex in VS Code: open ⚙️ → MCP servers → Add server, enter the following and save:
Name: fisheries-data
Type: STDIO
Command: the executable path printed by the installer
Arguments: leave empty
Claude Code: run from the repository folder:
$mcpExe = (Resolve-Path ".venv\Scripts\fisheries-data-mcp.exe").Path
claude mcp add --scope user --transport stdio fisheries-data -- "$mcpExe"Cowork: this repository does not yet provide its required plugin or remote connection. Use one of the clients above or Claude Desktop Chat.
In the repository folder, open:
notepad .envFill in the sources you will use and leave the others blank:
BARENTSWATCH_CLIENT_ID=your_client_id
BARENTSWATCH_CLIENT_SECRET=your_client_secret
COPERNICUSMARINE_SERVICE_USERNAME=your_username
COPERNICUSMARINE_SERVICE_PASSWORD=your_password
UN_COMTRADE_API_KEY=your_subscription_keySave .env beside install.py. FishStat needs no credentials. UN Comtrade downloads require each user's own free API subscription key; reference-code searches remain public. Obtain the other credentials by registering a BarentsWatch API client or creating a Copernicus Marine account.
Restart the Codex extension or close and reopen Claude Code. Start a conversation:
Use Fisheries Data MCP. I want to study salmon production, production value and sea lice in Norway. Which datasets could help? Explain their periods, units and observation levels, and tell me which ones you can download.
Downloads are saved by default to ~/fisheries-data-mcp/exports with source metadata.
For macOS/Linux, other clients and configuration options, see the detailed installation guide.
These steps update the existing installation in C:\Users\adams\research\fisheries-data-mcp, which Codex already uses. If you cloned the repository elsewhere, change the path in the first command.
Close VS Code and Codex to release the MCP executable. Open a separate PowerShell window.
Run these commands in order:
Set-Location 'C:\Users\adams\research\fisheries-data-mcp'
git pull --ff-only
py -3 install.pyOpen the credentials file with notepad .env. Add this line with your UN Comtrade key, then save the file:
UN_COMTRADE_API_KEY=your_keyIf the variable already exists, update its value instead of adding a duplicate.
Reopen VS Code and Codex. The search_comtrade_reference and comtrade_trade_records tools should appear.
The installer preserves .env and your existing keys. You do not need to change the MCP configuration because Codex still uses the executable in the same folder.
FAQ: example requests, GitHub basics, updates and troubleshooting.
Technical reference: tools, output formats, units, limitations and developer checks.
FAO inventory notes and BarentsWatch inventory notes: catalogue coverage and verification evidence.
Retrieve weekly mean adult female salmon lice for a Norwegian aquaculture locality and year.
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | ||
| locality_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral context. 'Retrieve' implies a read-only operation, and the description clarifies the aggregation level ('weekly mean') and organism/sex ('adult female salmon lice'). It does not mention output structure, possible empty results for invalid locality/year, or data source quirks, so it is only partially transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single well-structured sentence that front-loads the action and resource, then adds the two scoping dimensions (locality and year). There is no filler, repetition, or schema duplication.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple with only two required parameters, but there is no output schema and no mention of whether the result is a time series of weekly values or a single summary value. The description also lacks guidance on how to obtain valid locality IDs or which years are available, leaving some important context missing for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the prose must compensate for the bare parameter names. The description adds that locality_id refers to a 'Norwegian aquaculture locality' and that year is the data year, but it gives no range, format, or source for valid locality IDs and years. This is helpful but incomplete.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Retrieve'), a precise resource ('weekly mean adult female salmon lice'), and a clear scope ('Norwegian aquaculture locality and year'). This fully differentiates it from the unrelated sibling tools about fisheries production, Copernicus datasets, and data sources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: whenever weekly adult female salmon lice data for a specific Norwegian locality and year is needed. However, it does not explicitly state any exclusions, prerequisites, or alternatives, though the sibling tools are dissimilar enough that ambiguity is low.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Describe a Copernicus Marine dataset's variables, units, coverage, version and product DOI before choosing a subset.
| Name | Required | Description | Default |
|---|---|---|---|
| dataset_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of explaining behavior, and it does state the tool is an informational describe operation returning dataset metadata. However, it omits output format, whether any auth/availability constraints apply, and error/edge-case behavior, leaving the behavioral contract incomplete for a no-annotation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence, no filler, front-loaded with the specific verb and resource. The 'before choosing a subset' clause adds workflow guidance without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter metadata inspection, the description covers what will be returned at a high level and when to call it. It falls short of fully complete because it does not tell an agent where dataset_id originates (e.g., search_copernicus_datasets) or what the response structure will be, though the absence of an output schema lowers that burden.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole required parameter dataset_id is not mentioned in the description; 'a Copernicus Marine dataset' only implicitly points at it. With 0% schema coverage, the description should state what dataset_id looks like or where it comes from, but it does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description identifies a clear subject ('a Copernicus Marine dataset') and a specific set of metadata outputs (variables, units, coverage, version, DOI), with 'Describe' as the verb. This distinguishes it from sibling subset_copernicus_dataset, and from search_copernicus_datasets which would be find/list rather than inspect.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'before choosing a subset' explicitly situates the tool in the workflow before subset_copernicus_dataset, telling an agent when to invoke it. It does not name search_copernicus_datasets as the way to obtain dataset_id or state when not to use the describe tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find annual production tonnes by FAO country/area for an aquatic species or group; export a CSV. Source: all, capture or aquaculture. Optionally set an exact ASFIS species_code. The weight basis depends on the species group.
| Name | Required | Description | Default |
|---|---|---|---|
| year | Yes | ||
| query | Yes | ||
| source | No | all | |
| species_code | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions the output format ('export a CSV') and a key behavioral caveat ('The weight basis depends on the species group'), which is useful. However, it does not disclose whether the operation is read-only, any authentication or rate-limit requirements, or the nature of the data returned beyond 'production tonnes'. It provides some transparency but leaves significant gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the core purpose, and then provides key parameter details. Every word is informative; there is no redundancy or filler. It efficiently communicates the tool's function and main options.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, no output schema, and no annotations, the description covers the main functionality, output format, and the species_code/source options. It mentions the weight basis caveat. However, it lacks details on expected input formats (e.g., year as integer, query syntax), any pagination or limits, and the structure of the returned CSV. It is adequate but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It explains the 'source' parameter by enumerating its values ('all, capture or aquaculture') and clarifies 'species_code' as 'exact ASFIS species_code'. It implicitly explains 'query' as the aquatic species or group. However, it does not detail the format or range for 'year', nor does it explain how 'query' interacts with 'species_code'. The description adds value but does not fully cover all parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Find'), a resource ('annual production tonnes by FAO country/area'), and a purpose ('for an aquatic species or group; export a CSV'). It clearly distinguishes itself from siblings like search_fishstat_species, which is for species lookup, and the copernicus tools, which are unrelated. The resource and scope are unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives context on the 'source' parameter ('all, capture or aquaculture') and mentions an optional species_code, which implies when to use those. However, it does not explicitly state when to use this tool versus alternatives, nor does it mention any exclusions (e.g., 'use search_fishstat_species to find species codes'). The usage context is present but not fully explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List connected sources and their coverage so the assistant can choose the right one.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral burden. It discloses that the tool performs a listing operation and returns source coverage information, implying a read-only catalog action. It does not detail return format or connection requirements, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no filler. It states the action, the object, and the purpose in that order, and every word contributes to understanding the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no parameters and no output schema, the description adequately states the basic return concept, but 'coverage' is left vague. It does not explain what dimensions of coverage are included or how the listed sources map to the sibling tools, which an agent would need for reliable source selection.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is trivially 100%. With no parameters to document, the description does not need to add parameter-level meaning. The baseline for zero-parameter tools is appropriately 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: 'List connected sources and their coverage.' The purpose is also explicit: 'so the assistant can choose the right one.' This clearly distinguishes it from the sibling tools, which are domain-specific search, describe, and subset operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: to choose the right data source among connected options. It does not explicitly name alternatives or state when not to use it, but the purpose sentence effectively communicates the intended usage moment.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search live Copernicus Marine catalogue for ocean variables and dataset IDs.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the behavioral disclosure burden. It does add some context with 'live' and indicates a read-only search, but it does not mention response structure, pagination, rate limits, or any other operational behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single focused sentence with no filler. It front-loads the key action and resource, and every word contributes to the core purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with no annotations and no output schema, the description is too thin. It states the high-level purpose but omits parameter semantics and any operational details, leaving an agent to guess how to construct a valid query and interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description does not explain the meaning or format of the query or limit parameters. The word 'search' weakly implies that query is a text search term, but limit and the expected query syntax are left completely unspecified.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Search'), a specific resource ('live Copernicus Marine catalogue'), and the expected output ('ocean variables and dataset IDs'). It is clearly distinguishable from sibling tools like describe_copernicus_dataset and subset_copernicus_dataset, which have different verbs and resources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as list_data_sources or describe_copernicus_dataset. There is no mention of when this search is appropriate or when a sibling should be chosen instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Find FishStat aquatic species or species groups by name or code, including oysters/ostras.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It only states the lookup function; it does not mention whether the operation is read-only, what the output looks like, pagination behavior, rate limits, or any other behavioral trait.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single sentence that is compact and front-loaded. It states the action, resource, lookup method, and a domain-specific example without filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter search tool, the description is minimally adequate: the required query's semantics are stated and limit is a common optional parameter. However, with no output schema and no annotation coverage, the absence of any detail about the response format or result behavior leaves a notable gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description clarifies that 'query' accepts a species name or code, which is useful. However, the 'limit' parameter is not described at all, and the unusual 'including oysters/ostras' clause adds no parameter-level detail. The description partially compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb ('Find') and resource ('FishStat aquatic species or species groups'), and adds the lookup mode 'by name or code'. It does not explicitly contrast with sibling search tools like search_copernicus_datasets, but the FishStat scope is clear enough to identify the tool's purpose.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this tool is for searching FishStat species by name or code, but it provides no guidance on when to prefer it over alternatives, when not to use it, or any prerequisites. No explicit usage versus sibling tools is given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Download a bounded Copernicus Marine subset by dataset, variable, bounding box and dates. Returns a local NetCDF, Zarr or CSV file with provenance.
| Name | Required | Description | Default |
|---|---|---|---|
| end | Yes | ||
| east | Yes | ||
| west | Yes | ||
| north | Yes | ||
| south | Yes | ||
| start | Yes | ||
| variable | Yes | ||
| dataset_id | Yes | ||
| file_format | No | netcdf |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations are absent, so the description must disclose behavior. It mentions the output (local NetCDF, Zarr or CSV with provenance) but does not describe side effects, network requirements, potential errors, or size limitations. As a download operation, it lacks details on how the file is delivered or whether it is a blocking call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that front-loads the main action and output. No unnecessary words, and it covers the essential purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 9-parameter tool with no annotations and no output schema, the description is incomplete. It does not explain parameter formats, prerequisites, or error handling, leaving an agent to guess required input conventions. The output is partially described but lacks details on how to access the file or any limitations.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must explain parameter meanings. It lists the roles (dataset, variable, bounding box, dates) but does not specify formats, units, or constraints for values like west/east coordinates or date strings. The file_format parameter is implied by the output mention but not explicitly defined.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb ('Download') and resource ('Copernicus Marine subset') with clear parameters (dataset, variable, bounding box, dates). Distinguishes from sibling tools like search_copernicus_datasets and describe_copernicus_dataset, which are about discovery rather than download.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, such as searching or describing datasets first. The description does not mention prerequisites like needing a valid dataset_id or any conditions that would make this tool inappropriate. It implies usage when a subset is needed but provides no exclusions or context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0barentswatch_lice_by_localitydescribe_copernicus_datasetfishstat_production_by_countrylist_data_sourcessearch_copernicus_datasetssearch_fishstat_speciessubset_copernicus_datasetScored across 7 tools
Each tool maps to a distinct action/resource: source listing, FishStat species lookup, production query, Barentswatch lice retrieval, and Copernicus search/describe/subset. The only mild adjacency is the two FishStat tools, but search versus production are clearly separated.
Most tools use verb_noun (list/search/describe/subset), but fishstat_production_by_country and barentswatch_lice_by_locality are noun phrases with source prefixes and no verb. This is a readable mixed convention, not chaotic, but it prevents a consistent pattern.
Seven tools cover three distinct data domains (FishStat, Barentswatch, Copernicus), plus source discovery without redundancy. The count is appropriate for a multi-source fisheries data server.
Copernicus is well covered with search/describe/subset, and FishStat covers species lookup plus production by source type. The Barentswatch integration is a single narrow endpoint retrieval, so the overall surface is somewhat thin on that source, but there are no critical dead ends for the advertised workflows.
Ask data questions in natural language. Get SQL, insights, and charts from your databases.
Discover, resolve, and query official Brazilian economic data with semantic search and provenance.
Query your org's data in natural language — read-only MCP access to SQL, NoSQL, files & warehouses.
Ask questions in plain language, get answers from your business database. No SQL required.
