almanac-mcp 0.3.0

MCP server for Almanac — Argentine financial data (BCRA, CNV, INDEC, SEC) for Claude Desktop, Cursor, Copilot

almanac-mcp

MCP server for Almanac — Argentine financial and economic data (BCRA, CNV, INDEC, SEC) exposed directly to your AI assistant (Claude Desktop, Cursor, Copilot, etc.) via the Model Context Protocol.

What it does

Once connected, your AI assistant can:

• List the catalog of published datasets (BCRA monetarias, tipos de cambio, INDEC IPC, CNV hechos relevantes, SEC EDGAR XBRL filings, and more)
• Inspect schemas column-by-column with descriptions, types, and pre-built example queries
• Run SQL directly against the production datasets — sub-second latency, cross-dataset JOINs work natively (e.g. join INDEC IPC with BCRA reservas, or SEC financial facts with CNV hechos relevantes by CUIT)
• Download full snapshots as signed parquet/CSV URLs to work locally with DuckDB, polars, pandas, R, or any other tool

v0.2 architecture (HTTP-only)

In v0.2 the client is a thin HTTP wrapper. No psycopg, no DuckDB, no parquet libs — the package installs in seconds and ships only mcp, httpx, and pydantic. All data plane operations are server-side at https://almanac.ar/api/mcp/v1/invoke. Benefits:

• Zero credentials on your machine (just ALMANAC_API_KEY)
• Schema discovery + AI metadata live server-side and update without a client version bump
• Telemetry and rate limits centralised

Requirements

• Python 3.10+
• An Almanac account on plan Pro+ or Enterprise (the MCP server is not part of the Pro tier)
• An API key generated at https://almanac.ar/account/api-keys

Install

uvx almanac-mcp                  # try it without installing
# or
pip install almanac-mcp          # persistent install

Configuration

The client requires ALMANAC_API_KEY in the environment. It optionally respects ALMANAC_SITE_URL (defaults to https://almanac.ar).

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "almanac": {
      "command": "uvx",
      "args": ["almanac-mcp"],
      "env": {
        "ALMANAC_API_KEY": "alm_your_key_here"
      }
    }
  }
}

Restart Claude Desktop. The Almanac tools appear automatically.

Cursor

~/.cursor/mcp.json:

{
  "mcpServers": {
    "almanac": {
      "command": "uvx",
      "args": ["almanac-mcp"],
      "env": { "ALMANAC_API_KEY": "alm_your_key_here" }
    }
  }
}

GitHub Copilot (VS Code)

Add to .vscode/settings.json:

{
  "github.copilot.chat.mcp.servers": {
    "almanac": {
      "command": "uvx",
      "args": ["almanac-mcp"],
      "env": { "ALMANAC_API_KEY": "alm_your_key_here" }
    }
  }
}

Tools

All four tools follow the <domain>.<action> naming convention:

catalog.list

Lists every published dataset with a brief summary. No params.

catalog.get(dataset_id)

Full metadata for a single dataset, including:

• Description, frequency, historical depth
• Business questions and typical use cases
• Methodology notes and known gotchas
• Pre-built example SQL queries
• mcp.table_name — exact Postgres table (e.g. data_bcra_monetarias_indicadores)
• mcp.columns — list of {name, type, nullable} to write SQL correctly

data.query(sql)

Runs a SELECT/WITH/EXPLAIN query against the production tables. DDL/DML are rejected. Server-side constraints:

• statement_timeout 30 s
• 10.000 row cap (truncation signalled in response)
• work_mem 32 MB

Response shape: { rows, row_count, truncated, columns }. Tables are documented through catalog.get (mcp.table_name).

data.snapshot_url(dataset_id, format="parquet")

Returns a 10-minute signed R2 URL to the complete production snapshot (parquet or CSV). Use this when you want to download the full dataset and work with it locally.

Example session

User: "What were Argentina's international reserves on the last business day, and how do they compare to a year ago?"

The assistant will:

1. Call catalog.list to see what is available.
2. Call catalog.get("bcra.monetarias.indicadores") to find the relevant variable and learn the table schema.
3. Call data.query with something like:

SELECT fecha, valor, unidad
FROM data_bcra_monetarias_indicadores
WHERE descripcion ILIKE '%reservas internacionales%'
  AND fecha <= CURRENT_DATE
ORDER BY fecha DESC
LIMIT 30

4. Compare the most recent value with the same date a year ago and reply with concrete numbers.

License

Proprietary. Use of this package requires an active Almanac subscription (plan Pro+ or Enterprise). See https://almanac.ar/pricing for details.

Support

• Documentation: https://almanac.ar/mcp
• Issues: https://github.com/nicolascolombo/Almanac/issues
• Email: [e-mail]