almanac-mcp 0.7.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

Architecture (HTTP-only)

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 (the hosted remote MCP endpoint for HTTP clients is https://mcp.almanac.ar/mcp). 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

Seven tools, named with underscores (Claude Desktop/web validate tool names against ^[a-zA-Z0-9_-]{1,64}$ and reject dots):

catalog_list

Lists every published dataset with a brief summary. Optionally pass a dataset_id to get full detail for one dataset. No required 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 table name (e.g. data_bcra_monetarias_indicadores)
• mcp.columns — list of {name, type, nullable} to write SQL correctly

data_summary(dataset_id)

Universal statistics for a dataset: row count, columns, and min/max/distinct ranges. Works on any published dataset without writing SQL.

data_distinct_values(dataset_id, column)

Frequency of unique values in a single column — useful to discover the domain of a categorical/dimension column before filtering.

data_query(sql)

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

• statement_timeout 60 s
• 50.000 row cap (truncation signalled in truncated)

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

data_query_parquet(dataset_id, sql)

Same as data_query but runs DuckDB server-side directly against the dataset's parquet snapshot in R2. Use for the large datasets that are not in Postgres (balances, deudores, plan-cuentas, bank indicators — anything catalog_list shows with queryable_via_sql=false). Higher caps than data_query: 100.000 row cap and 120 s timeout (calibrado para análisis B2B más pesado sobre parquet).

data_snapshot_url(dataset_id, format="parquet")

Returns a short-lived 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]