Metadata-Version: 2.4
Name: tradealmanac-mcp
Version: 2026.10.7
Summary: MCP server for the TradeAlmanac public API: dividends, screener, indicators, calendar effects
License-Expression: MIT
Project-URL: Homepage, https://tradealmanac.com/en/developers
Project-URL: Documentation, https://tradealmanac.com/en/developers/mcp
Keywords: mcp,model-context-protocol,moex,dividends,screener,tradealmanac
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# tradealmanac-mcp

<!-- mcp-name: com.tradealmanac/mcp-server -->

Russian version: the file `README.ru.md` in this package ·
[documentation in Russian](https://tradealmanac.com/ru/developers/mcp)

TradeAlmanac is a market-data, analytics and paper-trading platform for the
whole world of finance, investing and trading; the Russian market is its
deepest-covered market today, not the boundary of the product.

An MCP server for the [TradeAlmanac](https://tradealmanac.com/en/developers)
public API. It gives an AI agent access to dividends, a screener, sectors, the
platform's own indicators (sentiment of the Russian, US and crypto markets),
calendar effects and ready-made security rankings — through the same endpoints,
with the same key and the same quota as any other reader of the API.

Package version: **2026.10.7** (API contract `2026-09-06`).

## Install

```bash
pip install tradealmanac-mcp
```

No dependencies: the server lives in the environment of your editor, and there
is no reason to pull other packages into it.

## Setup

A key is issued in your account, section API. For a first try use the sandbox
key `afk_sandbox_tradealmanac_demo`: it spends no quota, and the answer is a
snapshot refreshed once a day.

**Claude Desktop** — `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tradealmanac": {
      "command": "tradealmanac-mcp",
      "env": { "TRADEALMANAC_API_KEY": "afk_your_key" }
    }
  }
}
```

**Cursor** — `.cursor/mcp.json` in the project or `~/.cursor/mcp.json`: the
same block.

**Claude Code** — one command:

```bash
claude mcp add tradealmanac --env TRADEALMANAC_API_KEY=afk_your_key -- tradealmanac-mcp
```

You can check that the key is accepted before touching any editor:

```bash
TRADEALMANAC_API_KEY=afk_sandbox_tradealmanac_demo tradealmanac-mcp --check
tradealmanac-mcp --tools        # the list of tools
tradealmanac-mcp --self-test    # the protocol without touching the network
```

## Language

English is the default language of tool titles, tool descriptions, parameter
descriptions, the server instructions and error messages. Set
`TRADEALMANAC_MCP_LANG=ru` to get all of them in Russian:

```json
"env": { "TRADEALMANAC_API_KEY": "afk_your_key", "TRADEALMANAC_MCP_LANG": "ru" }
```

Tool names, argument names and the fields of an answer are the same in both
languages. An unknown value falls back to English.

## Tools

| Tool | What it gives |
|---|---|
| `dividends_by_ticker` | payouts for one security with announcement statuses, the next record date |
| `dividends_calendar` | the record-date calendar across all securities for a period |
| `screener` | a screen by sector, P/E and dividend yield |
| `screener_fields` | screener fields and their units |
| `sectors` | sector codes and names |
| `list_indicators` | all indicators of the platform with the current value and zone |
| `get_indicator` | one indicator: value, zone, normalised components |
| `get_indicator_history` | daily history of an indicator |
| `get_almanac_effect` | calendar effects: statistics with the number of observations and significance |
| `list_rankings` | the list of ready-made security rankings |
| `get_ranking` | one ranking: places and relative discounts, without prices or multiples |
| `afgi` | a former name: the same as `get_indicator` with the identifier `afgi` |
| `afgi_history` | a former name: the same as `get_indicator_history` with the identifier `afgi` |
| `analysis_by_ticker` | the platform's write-ups for one security |
| `api_meta` | what the API serves and what it does not |

Indicators, calendar effects and rankings answer without a key too — with a
rate ceiling per address; indicator history older than a year needs a key.

## MCP registry

The metadata for the official registry is in `server.json` next to this file:
one server name, `com.tradealmanac/mcp-server`, and two packages — this one and
`@tradealmanac/mcp-server` on npm. A name in the namespace of a domain is
confirmed by the owner of the domain at publication.

## What is not here

Quotes, candles and the Moscow Exchange instrument directory — neither in real
time, nor delayed, nor from storage. There is no world market data either: the
platform has no licence to distribute it. A "share price" tool will not appear
in this server — and not because nobody got round to it.

## Ceilings

60 requests a minute and 1,000 a day per key; beyond that the answer is `429`,
and the server tells the agent in how many seconds to retry. It does not retry
on `429` itself: the quota is already exhausted, and a retry turns the ceiling
into a storm. A retry with a growing delay is made only for temporary refusals
(500, 502, 503, 504).

A tool answer is limited to 28,000 characters (`TRADEALMANAC_MCP_MAX_CHARS`).
If a selection is longer, lists are trimmed and the answer gets a `_truncated`
field with `shown_per_list` and `hidden_items` — a part of a selection is never
presented as the whole.

## Units

Yields and screener thresholds are fractions, not percentages:
`dividend_yield_min=0.08` means 8 %. A payout with a forecast status has not
been declared by the board of directors.

Licence: MIT.
