Skip to main content
Glama

anp-mcp

An MCP server that lets AI assistants (Claude, Cursor, and any MCP client) answer questions about Brazilian oil production, using ANP's well-level data harmonised from 2005 to today.

ANP publishes production per well, but not through an API: files change format over time, wells and contracts get renamed, and the online query is behind a captcha. This server works on a cleaned, harmonised snapshot of that data, published as an open dataset on Hugging Face, so you can simply ask:

"Which oil fields grew and declined the most in the last 6 months?"

Largest rises (Apr–Sep 2026 vs Oct 2025–Mar 2026)

Before (bbl/d)

Recent (bbl/d)

Change

Búzios

836,755

1,056,771

+26.3%

Mero

653,417

750,764

+14.9%

Bacalhau

32,119

99,492

+209.8%

Can you trust the numbers?

The sum of all wells reproduces ANP's official national production within ±1% in every one of the 261 months from January 2005 to September 2026 (worst month: +0.52%, March 2008). The server exposes this check as a tool, so the assistant can show it whenever it answers.

Related MCP server: mcp-dados-brasil

Evals: does it answer correctly?

Eval results: pass rate before and after the server changes, and Sonnet vs Haiku

21 questions with answers computed from the dataset, each asked 3 times, scored by a grader that also checks where every figure came from. The server changes added 12 points under both graders, and no answer from the improved server was failed for invented data. Claude Haiku 5.5 passes 87% at 1/21 of the cost per answer of Claude Sonnet 5.5. Details: evals/RESULTS.md.

Read-only by design: tools run fixed, parameterised queries; no tool can write files or run arbitrary SQL.

Tools

Tool

What it answers

search_field_groups

Find a field by name (accent-insensitive): "buzios" → BÚZIOS

field_group_production

Monthly production (bbl/d) and active wells of one field

top_changes

Fields that grew or declined the most over the last N months, with the method

national_reconciliation

The trust check above: summary by default, every month on request

national_production

Brazil's total petroleum production (bbl/d, onshore/offshore) from ANP's national series, by month or by year; incomplete years are flagged

A field group is the unit used here: fields that were renamed, merged or split by contract are grouped (e.g. TUPI includes LULA), so a series does not break when ANP changes a name.

How it works

ANP raw files  ->  harmonisation pipeline  ->  open dataset (Hugging Face, versioned)
                                                     |  downloaded once, then cached
                     your AI assistant  <-  anp-mcp (DuckDB, runs on your machine)

On first use the server downloads the two small files it needs from the dataset and caches them; after that it works offline. It is pinned to one dataset version, so answers do not change silently when a new month is published. No database to install, no account needed, and your questions are not sent anywhere except to your own AI assistant. Units: petroleum = oil + condensate, daily rate (bbl/d).

Install

Requires uv.

Install without cloning

The server runs straight from GitHub; on the first tool call it downloads the dataset from Hugging Face and caches it locally.

Claude Code

claude mcp add anp-mcp -- uvx --from git+https://github.com/lorenamelos/anp-mcp anp-mcp

Claude Desktop (or any MCP client using a JSON config, e.g. claude_desktop_config.json), then restart the client:

{
  "mcpServers": {
    "anp-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/lorenamelos/anp-mcp", "anp-mcp"]
    }
  }
}

From a local clone (for development)

git clone https://github.com/lorenamelos/anp-mcp.git

Point your MCP client at the clone, then restart the client:

{
  "mcpServers": {
    "anp-mcp": {
      "command": "uv",
      "args": ["--directory", "/path/to/anp-mcp", "run", "anp-mcp"]
    }
  }
}

Optional environment variables (both install modes):

Variable

Default

Use

ANP_MCP_REVISION

v2026.09

Dataset version to read

ANP_MCP_DATASET

lorenamelos/anp-oil-production

Dataset repository

ANP_MCP_DATA_DIR

not set

Read the dataset files from a local folder instead

Limitations

  • A snapshot, not a live feed: ANP publishes each month about two months later, and the dataset is updated by release.

  • Production only (petroleum, wells, fields). Gas detail and royalties are planned.

  • Field groups follow documented, rule-based grouping; another analyst could group some edge cases differently.

Data and licence

Data: Agência Nacional do Petróleo, Gás Natural e Biocombustíveis (ANP), open data, harmonised in the anp-oil-production dataset (CC BY 4.0). This is an independent project, not affiliated with ANP. Code: MIT.

Built by Lorena Melo.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server that provides real-time access to Brazilian public data from 6 official sources via 11 read-only tools, including Pix, IBGE, Câmara dos Deputados, Senado Federal, Diário Oficial da União, and Agência Brasil, with no API key required.
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Maps corporate affiliations of a Brazilian individual from CPF for anti-money laundering (AML) due diligence. Read-only hosted MCP server with one tool, works with any MCP-compatible client.
      MIT