Metadata-Version: 2.4
Name: almanac-mcp
Version: 0.7.0
Summary: MCP server for Almanac — Argentine financial data (BCRA, CNV, INDEC, SEC) for Claude Desktop, Cursor, Copilot
Project-URL: Homepage, https://almanac.ar
Project-URL: Documentation, https://almanac.ar/mcp
Project-URL: Source, https://github.com/nicolascolombo/Almanac
Author: Nicolás Colombo
License: Proprietary
Keywords: almanac,argentina,bcra,claude,cnv,financial-data,indec,mcp,sec
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.0
Requires-Dist: pydantic>=2.8
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.7; extra == 'dev'
Description-Content-Type: text/markdown

# almanac-mcp

MCP server for [Almanac](https://almanac.ar) — 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

```bash
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):

```json
{
  "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`:

```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`:

```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:

```sql
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: contacto@almanac.ar
