mcp-nbim CLAUDE.md

NBIM MCP Server

MCP server for querying Government Pension Fund Global (GPFG) data from NBIM.

Architecture

• Framework: FastMCP on streamable-http (port 8008) or stdio
• Data sources: NBIM JSON API (nbim.no/api/investments/v2/) for holdings and fund value; web scraping for returns and exclusions
• Caching: In-memory with per-key TTL (holdings: 24h, init: 1h, exclusions: 6h)
• No external credentials required — all data is public

Project structure

• mcp_nbim/server.py — FastMCP instance, tool registration, transport
• mcp_nbim/tools.py — 6 MCP tool functions with formatting
• mcp_nbim/client.py — NBIMClient (JSON API + web scraping + cache)
• mcp_nbim/config.py — URLs, TTLs, asset class maps, country names, fallback data
• mcp_nbim/entry_prompt.py — MCP prompt describing available tools
• pyproject.toml — Package metadata and entry point

Running

mcp-nbim              # streamable-http on port 8008
mcp-nbim --stdio      # stdio transport
python -m mcp_nbim    # alternative

Tools

1. nbim_fund_value() — Fund value + asset allocation from init.json NAV data
2. nbim_holdings_search(query, year, country, sector) — Search equity holdings
3. nbim_top_holdings(n, year, country, sector) — Top N by market value
4. nbim_country_allocation(year, asset_class, top_n) — Geographic allocation from history API
5. nbim_returns(start_year, end_year) — Annual returns (scraped + hardcoded fallback)
6. nbim_exclusions(query, category, criterion) — Excluded companies (scraped HTML table)

Data notes

• Holdings JSON contains equities only (at=0). Fixed income requires Snowflake (Phase 2).
• The init.json NAV array has values in raw numbers (divide by 1e9 for billions).
• History JSON organizes data by country with parallel arrays for years and values.
• Returns scraping parses Highcharts Date.UTC() patterns from inline JavaScript.