Fetches the open dataset 'Brazil Port Data: consolidated ANTAQ port statistics, 2010-2026' from the Zenodo API, providing the MCP server with real port data for its tools.
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., "@port-emissions-mcp Rank Itaqui, Santos and Paranaguá by average waiting time in 2025."
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.
An MCP server that lets Claude estimate the at-berth CO₂ of tankers and answer questions about Brazilian ports (247 ANTAQ installations, 2010 to 2026), with the source and the method behind every number
The Model Context Protocol (MCP) lets an AI assistant call external tools. This server gives Claude six tools that join two pieces of my work: the maritime-co2 library (at-berth CO₂ of liquid-bulk vessels, IMO Fourth GHG Study 2020 method) and the Brazil Port Data tables (ANTAQ statistics aggregated with the same filter as the agency's public panel).
With it, Claude can answer questions such as:
"How long did ships wait to berth at Itaqui, Paranaguá, Santos and Ponta da Madeira in 2025? Rank them."
"Give me the cargo profile of Itaqui since 2019, split by deep sea and cabotage."
"A 45,000 DWT tanker stayed 67 hours at berth. How much CO₂ would shore power have avoided?"
"Here are 40 calls with DWT and hours at berth. What is the total OPS-avoidable CO₂ by size band?"
Tool | What it does |
| Searches installations by name, port complex or ANTAQ code ("Ponta da Madeira" → |
| Year-by-year cargo (tonnes), navigation mix, berthings and port times for one installation |
| Ranks several installations on tonnes, berthings, waiting time, hours at berth or total stay |
| At-berth CO₂ of one tanker call (auxiliary engine, the load shore power replaces) |
| The same for a list of calls, with totals by size band |
| Formula, parameters and sources behind the numbers |
Design choices that matter when an LLM is the user:
Every answer carries its source, and the server instructions tell Claude to cite it and to flag partial years (2026 rows cover only part of the year).
Names resolve to codes safely. An exact name wins ("Paranaguá" is the public port, not the Cattalini terminal); an ambiguous name returns the candidate codes so Claude can ask or choose, instead of guessing.
Errors are written for the model. "No installation matches 'xyz'. Use find_installation first." lets Claude correct itself in the next step.
Caveats travel with the CO₂ numbers. Auxiliary power and load factor are illustrative defaults by DWT band, and the tool says so.
Related MCP server: Trimtab AIS
The server looks for the port tables in this order:
The folder in PORT_DATA_DIR, if set (for your own copy or a newer extraction).
The open dataset on Zenodo, after one command:
port-emissions-mcp downloadThis fetches Brazil Port Data: consolidated ANTAQ port statistics, 2010-2026 (doi:10.5281/zenodo.XXXXXXX, ODbL 1.0) into ~/.cache/port-emissions-mcp.
A small synthetic dataset bundled in src/port_emissions_mcp/example_data/ (three fictitious installations), so the tests run offline. Every answer based on it carries a warning that the numbers are invented.
File | Grain |
| year × installation, tonnes |
| year × installation, tonnes by navigation type |
| year × installation, berthings |
| year × installation, mean hours waiting, operating, at berth, total stay |
| installation names (linked to ANTAQ codes by tonnage in 2024 and 2025, one-to-one matches only) |
Requires Python 3.10+ and uv (or pip).
git clone https://github.com/darlianecunha/port-emissions-mcp
cd port-emissions-mcp
uv venv && uv pip install -e ".[test]"
uv run pytest # 9 tests, offline, synthetic data
uv run port-emissions-mcp download # real data from Zenodoclaude mcp add --transport stdio --env PORT_DATA_DIR=/path/to/dados-consolidados \
port-emissions -- /path/to/port-emissions-mcp/.venv/bin/port-emissions-mcpLeave out --env ... if you ran port-emissions-mcp download. Check with claude mcp list.
Add to claude_desktop_config.json (Settings → Developer → Edit Config) and restart the app:
{
"mcpServers": {
"port-emissions": {
"command": "/path/to/port-emissions-mcp/.venv/bin/port-emissions-mcp",
"env": {}
}
}
}Path | Content |
| The six MCP tools and the server instructions |
| Loading, name-to-code linking, search and resolution |
| Fetches the open dataset from the Zenodo API (standard library only) |
| Synthetic data (invented numbers) |
| pytest suite: tools, name resolution, MCP exposure, and a download from a local mock of the Zenodo API |
| Prompts used to test the server with Claude |
At-berth CO₂ (via maritime-co2, doi:10.5281/zenodo.20708090): CO₂ = aux_kW × load_factor × hours × SFOC / 10⁶ × Cf, auxiliary engine only (boilers excluded because they keep running for cargo heating). Cf from the IMO Fourth GHG Study 2020: MDO/MGO 3.206, HFO 3.114 t CO₂/t fuel; SFOC 215 g/kWh. Scope: liquid-bulk (tanker) vessels.
Data licence. The port tables are ODbL 1.0, derived from ANTAQ open data; cite the Zenodo record. The code is MIT.
Cargo follows ANTAQ's definition of port movement (authorised operations that count as movement), so national totals match the agency's panel.
Berthings count distinct records with authorised cargo operations, so they are lower than raw ANTAQ berthing counts.
Port times are annual means per installation.
Limitations. Size-band parameters are illustrative, not vessel-specific. 2026 is partial. 71 of 247 codes have no linked name and are labelled with their port complex.
maritimeco2: the CO₂ library this server calls
decarbport.com: interactive calculator using the same method
brazilportdata.com: public panels built from the same ANTAQ tables
MCP_DadosPublicosANTAQ: a broad MCP server over many ANTAQ and trade archives. This project is narrower by design: curated annual series that match ANTAQ's official totals, plus at-berth CO₂ and method caveats in every answer
Cunha, D. R. (2026). port-emissions-mcp: an MCP server for at-berth CO₂ and Brazilian port statistics (Version 0.1.0) [Software]. https://github.com/darlianecunha/port-emissions-mcp
Darliane Ribeiro Cunha, PhD. ribeirocunha.com · ORCID 0000-0003-2548-1237
MIT.
Compare several installations on one indicator in one year, ranked high to low.
Args: installations: ANTAQ codes or unambiguous names. indicator: tonnes, berthings, waiting_hours, hours_at_berth or total_stay_hours. year: reference year.
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | ||
| indicator | Yes | ||
| installations | 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. It does disclose a real behavioral trait, the high-to-low ranking of results, which is useful. However it omits error behavior for invalid codes/ambiguous names, permission needs, and data availability limits, leaving real gaps for an unannotated 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?
The purpose sentence is front-loaded and waste-free, with parameters in a tidy Args block. The indicator enumeration duplicates the schema enum, which is the only mild 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 3-param tool with no annotations and no output schema, the description covers purpose, ordering, and parameter meaning, but omits the year default (2025), invalid-input behavior, and any indication of the result shape beyond ranking, so it is adequate rather than complete.
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 and largely does: it explains that installations accept ANTAQ codes or unambiguous names and clarifies the year is a reference year. The indicator list merely repeats the schema enum, and the year default of 2025 is not mentioned, but the added meaning for installations is substantive.
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 (compare), resource (installations/ports), and scope (one indicator, one year), plus the output ordering. It differentiates itself functionally from single-entity siblings like port_profile, though it does not name them explicitly.
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?
Usage is implied by 'compare several installations on one indicator' – a multi-entity, single-metric comparison – but there is no explicit when-to-use, when-not, or named alternative among siblings such as port_profile or find_installation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimate the at-berth CO2 of ONE liquid-bulk (tanker) call from the auxiliary engine, i.e. the CO2 that Onshore Power Supply (shore power) would avoid. Boilers are excluded.
Args: dwt: deadweight tonnage of the vessel. berth_hours: hours at berth (from berthing to unberthing). fuel: fuel burnt by the auxiliary engine. sfoc_g_per_kwh: specific fuel oil consumption, default 215 g/kWh.
| Name | Required | Description | Default |
|---|---|---|---|
| dwt | Yes | ||
| fuel | No | MDO | |
| berth_hours | Yes | ||
| sfoc_g_per_kwh | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It discloses meaningful scope constraints (auxiliary engine only, boilers excluded, liquid-bulk tankers only), which an agent needs. However, it says nothing about the nature of the operation (deterministic read-only computation) or the units/format of the returned CO2 figure.
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 purpose sentence is dense but front-loaded and the argument list is compact and scannable. There is no filler; a slightly long opening clause is the only cost.
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?
Purpose, scope, and all parameters are covered for a 4-param tool with no annotations and no output schema. The main gap is that nothing indicates the form or units of the returned estimate, and no sibling routing is offered for the single-call versus multi-call distinction.
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, and it does: all four parameters are documented with meaning (dwt=deadweight tonnage, berth_hours=berthing to unberthing, fuel=burnt by auxiliary engine, sfoc default 215 g/kWh). It does not restate the fuel enum values or the CO2 output units, but the per-parameter coverage is strong.
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 (estimate), resource (at-berth CO2), and narrows scope to ONE liquid-bulk (tanker) call, the auxiliary engine, and explicitly excludes boilers. The 'ONE ... call' phrasing implicitly distinguishes it from the sibling estimate_calls_co2 without needing to open either schema.
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?
Scope limits (single call, liquid-bulk tanker, auxiliary engine only, boilers excluded) imply when the tool applies, but there is no explicit when-to-use versus estimate_calls_co2 or the other siblings, and no stated prerequisites. Usage is inferable rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Estimate at-berth (OPS-avoidable) CO2 for MANY liquid-bulk calls and sum it.
Args: calls: list of objects with keys "dwt" and "berth_hours" (optional "call_id"). fuel: fuel burnt by the auxiliary engine.
| Name | Required | Description | Default |
|---|---|---|---|
| fuel | No | MDO | |
| calls | 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. It does disclose behavioral traits beyond the schema, notably that results are summed across calls and that the CO2 is 'OPS-avoidable' at berth, but it says nothing about units, authorization, error handling, or how missing call data is treated.
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 short, front-loaded with the core purpose, and uses a compact Args block. It is efficiently sized, with only minor imprecision in the fuel definition.
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 annotations and no output schema, the description does not state what the return value looks like (e.g. total CO2 in tonnes vs kg, per-call breakdown vs single sum), which matters for an aggregation endpoint. Inputs and the summing behavior are reasonably covered, but the missing output framing leaves a real 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 compensates by documenting the nested object keys ('dwt', 'berth_hours', optional 'call_id') that the schema's open item object does not define. However, its explanation of 'fuel' as 'fuel burnt by the auxiliary engine' is imprecise for what the schema shows to be a fuel-type enum (MDO/MGO/HFO).
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 and resource: estimate at-berth (OPS-avoidable) CO2 for liquid-bulk calls and aggregate. The emphasis on 'MANY' and 'sum it' implicitly separates it from the singular sibling estimate_berth_co2, but it never names that sibling, so the differentiation is inferred rather than stated.
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?
Usage is only implied: 'MANY liquid-bulk calls' suggests this is the batch counterpart to estimate_berth_co2, but there is no explicit when-to-use, when-not, or alternative routing (e.g. for a single call or a non-liquid-bulk vessel). An agent must infer the choice from the plural wording.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explain the method, parameters and sources behind a tool's numbers.
| Name | Required | Description | Default |
|---|---|---|---|
| topic | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden, and it does disclose what the response contains (method, parameters, sources) for a read-style explainer. However, it omits any statement of side effects, permissions, or rate limits, and does not clarify whether it is a pure lookup.
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 front-loaded sentence with no filler. It is efficient, though arguably too terse given the parameter documentation gap.
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?
An output schema exists, so return values need not be spelled out, and a single enum parameter keeps the surface small. Still, the description does not connect the enum topics to the sibling estimation tools, which is the key context an agent needs to call this correctly.
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 coverage is 0%, so the description should explain the 'topic' parameter, but it only says 'a tool's numbers' generically. It never maps the three enum values (berth_co2, port_statistics, port_times) to the methods or sibling tools they correspond to, leaving the agent to guess.
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 ('Explain') and a specific resource ('the method, parameters and sources behind a tool's numbers'), which tells the agent this is a meta/documentation tool rather than an estimator. It does not explicitly name how it differs from siblings like estimate_berth_co2, so it stops short of a 5.
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?
There is no when-to-use guidance, no prerequisite, and no mention of the sibling tools whose numbers it explains. The agent must infer from the enum values that this is the companion to the estimation tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Brazilian port installations (public ports and private terminals) by name, port complex or ANTAQ code, e.g. "Itaqui", "Ponta da Madeira", "Paranagua", "BRSSZ". Returns ANTAQ codes to use in the other tools.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It discloses the searchable fields and the return content (ANTAQ codes), which is genuinely useful, but says nothing about match behavior, result limits, ambiguity handling, or whether authentication is needed for a read-only search.
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?
Two sentences, zero waste, purpose front-loaded before the return-value note. The example values earn their place by clarifying that both names and codes are acceptable input.
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?
With no output schema, the description usefully states what comes back (ANTAQ codes) and why. It is nearly complete for a one-parameter search, but leaves open what happens with partial or ambiguous matches and whether multiple installations can be returned.
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 single 'query' parameter has 0% schema description coverage, so the description must compensate — and it does, by naming the three accepted match domains (name, port complex, ANTAQ code) and giving four concrete example values including a code format like 'BRSSZ'.
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 (Search) and a precisely scoped resource (Brazilian port installations, public ports and private terminals). It is clearly distinguishable from siblings like port_profile or compare_ports, which consume the codes this tool produces.
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 sentence 'Returns ANTAQ codes to use in the other tools' makes the workflow position clear: this is the discovery/lookup step that feeds the other tools. It does not name a specific alternative or state when not to use it, so it stops short of explicit when/when-not guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Year-by-year profile of one installation: cargo handled (tonnes), split by navigation type, number of cargo berthings and mean port times (waiting, operation, at berth).
Args: installation: ANTAQ code (e.g. BRIQI) or an unambiguous name. start_year, end_year: period, inclusive (data from 2010).
| Name | Required | Description | Default |
|---|---|---|---|
| end_year | No | ||
| start_year | No | ||
| installation | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full disclosure burden, and it does supply real behavioral context: it enumerates the returned metrics and flags a data boundary ('data from 2010'). It does not explicitly declare read-only semantics or note pagination/limits, but the descriptive, non-mutating framing is unambiguous.
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?
Front-loaded with the tool's scope, then a compact Args block. Every clause adds information (measures, units, split dimension, period semantics, data floor) with no redundancy or filler.
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?
With no output schema and 0% schema description coverage, the description properly takes on the return-value explanation and documents all three parameters. It is complete for correct invocation, though it could have been stricter about defaults and the read-only nature.
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 coverage is 0%, so the description must compensate, and it does: it explains 'installation' accepts an ANTAQ code (with example BRIQI) or an unambiguous name, and defines start_year/end_year as an inclusive period with a floor of 2010. It omits the schema defaults (2019/2025), which is a minor 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?
States a specific verb and resource ('Year-by-year profile of one installation') and enumerates the exact metrics returned: cargo handled in tonnes by navigation type, cargo berthings, and mean waiting/operation/berth times. This is far more specific than the sibling tools (estimate_*_co2, compare_ports, find_installation), so an agent can distinguish purpose without opening the schema.
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?
Usage is implied rather than stated: the profile is scoped to 'one installation,' which implicitly contrasts with compare_ports (multiple) and suggests find_installation to resolve the code. However, there is no explicit when-to-use/when-not or named alternative, leaving the agent to infer the routing.
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.0compare_portsestimate_berth_co2estimate_calls_co2explain_methodfind_installationport_profileScored across 6 tools
The two estimator tools are distinguished by scale (ONE call vs MANY calls), and port_profile (single installation over time) vs compare_ports (several installations in one year) are clearly differentiated. There is minor overlap in purpose between the two CO2 estimators, but descriptions make the intent clear.
Most tools follow a verb_noun pattern (estimate_berth_co2, estimate_calls_co2, find_installation, compare_ports, explain_method). port_profile deviates from this pattern by using noun_noun, a minor inconsistency.
Six tools is well-scoped for a niche port-emissions analysis domain. Each tool—single estimation, batch estimation, lookup, profile, comparison, and method explanation—earns its place without redundancy.
The surface covers the core lifecycle: finding installations, profiling, comparing, estimating emissions, and explaining methods. Minor gaps exist, such as no direct tool to enumerate all installations or aggregate multi-year comparisons, but agents can work around these.
Pay-per-call shipping evidence: canal queues, tanker flows, container and carbon exceptions.
Port delay exposure with p50/p90 confidence intervals, demurrage impact and a free public feed.
IBGE: geography, census, economy and health from the official APIs, with provenance. 23 tools.
Signed global shipping & commodity data: oil, LNG, grain, sanctions, fleet, emissions.
