TradeAlmanac
Sign in
Documents

Connecting AI agents

An MCP server that serves TradeAlmanac data straight into Claude, Cursor and other agent environments — with your own key and the same quota as any other reader.

MCP is an open way to give a model access to a data source: the agent sees a list of tools and calls them itself when an answer needs them. Our server is a thin wrapper over the same machine interface described on the developers page: it adds no data of its own and no load of its own, and it works with your reader key.

Installation

Python — the tradealmanac-mcp package
pip install tradealmanac-mcp

# проверить ключ до всякого редактора
TRADEALMANAC_API_KEY=afk_… tradealmanac-mcp --check
Node — the same server, no install
npx -y @tradealmanac/mcp-server --tools

The two implementations are equivalent: same tools, same limits, same answers, one shared manifest. Pick whichever runtime is already on your machine. Neither has dependencies — the server runs inside your editor's environment, and there is no reason to drag third-party packages in there.

Claude Desktop

claude_desktop_config.json
{
  "mcpServers": {
    "tradealmanac": {
      "command": "tradealmanac-mcp",
      "env": { "TRADEALMANAC_API_KEY": "afk_…" }
    }
  }
}

The file lives in the application settings, under «Developer». Restart Claude Desktop after editing it — the tool list is read once at start-up.

Cursor

.cursor/mcp.json in a project, or ~/.cursor/mcp.json
{
  "mcpServers": {
    "tradealmanac": {
      "command": "npx",
      "args": ["-y", "@tradealmanac/mcp-server"],
      "env": { "TRADEALMANAC_API_KEY": "afk_…" }
    }
  }
}

A config inside a project applies to that project only; the one in your home directory applies everywhere. Other agent editors understand the same block — the MCP configuration format is shared.

Claude Code

One command, no files to edit
claude mcp add tradealmanac \
  --env TRADEALMANAC_API_KEY=afk_… -- tradealmanac-mcp

The key

Keys are issued free of charge in your account, under «API». There is a sandbox key for a first try: it consumes no quota, but it answers with a daily snapshot, so it will not show you fresh numbers.

Trying it with the sandbox key
TRADEALMANAC_API_KEY=afk_sandbox_tradealmanac_demo tradealmanac-mcp --check

Three scenarios

  • Build a screen — «Find oil and gas names with a dividend yield above 8 % and a P/E below 6, show them as a table.» The agent will fetch the sector codes, check the units of each field, and run the screener itself.
  • Compare dividends — «Compare the dividend history of Sberbank and Lukoil over five years and tell me whose payouts are more regular.» The answer carries announcement statuses: a forecast must be called a forecast.
  • Export the calendar — «Export the upcoming record dates through the end of the year to CSV.» The calendar is paged by cursor, and saving the file is done by the editor itself.

What the agent will not get here

MOEX quotes, candles and the instrument reference are not part of the contract — not in real time, not delayed, not from storage; neither is global market data. A «share price» tool will not appear in this server, and that is a licensing boundary rather than an omission. The server tells the model so on the very first connection: an agent with nothing to answer must say so, not borrow a number from elsewhere and sign our name under it.

Limits

The quota is your own — the key's quota: 60 requests a minute and 1 000 a day on a free key. When it runs out, a 429 arrives with the number of seconds to wait, and the server does not retry on its own: retrying into an exhausted quota turns a ceiling into a storm. Tool answers are capped in size; if a selection is longer, the answer carries a note saying how many records were hidden — part of a selection is never passed off as all of it.

Questions about access and requests for higher limits go through contacts.

Connecting AI agents — TradeAlmanac