For AI agents

Data Access for AI Agents

Annalist data is available as JSON, CSV and Excel, through a read-only MCP server and with a description for language models, so that an agent can quote a figure with its document. Access requires no account or key.

MCP server

https://annalist-fin.pages.dev/mcp

Streamable HTTP, JSON responses, no session. Read-only tools.

Guide for models

/llms.txt and /llms-full.txt

The coverage, the conventions and how to cite, in the llms.txt format.

API description

/api/v1/openapi.json

OpenAPI 3.1 description of the static JSON and CSV endpoints.

Company list

/api/v1/companies.json

Ids, names, tickers and the latest snapshot of each company.

Workbook

/company/{id}/{id}.xlsx

One Excel workbook per company, with its statements, ratios, findings and checks.

Connect an Agent

Any client that supports remote MCP servers over HTTP can use the server URL above.

Claude Code

claude mcp add --transport http annalist https://annalist-fin.pages.dev/mcp

Project Configuration (.mcp.json)

{
  "mcpServers": {
    "annalist": { "type": "http", "url": "https://annalist-fin.pages.dev/mcp" }
  }
}

Python Without an MCP Library

A request to the MCP server is one JSON-RPC message in a POST, so a tool call needs no session and no initialize request first.

Python Standard Library

import json, urllib.request

body = {"jsonrpc": "2.0", "id": 1, "method": "tools/call",
        "params": {"name": "search_companies",
                   "arguments": {"query": "AAPL"}}}
req = urllib.request.Request(
    "https://annalist-fin.pages.dev/mcp",
    data=json.dumps(body).encode(),
    headers={"Content-Type": "application/json",
             "Accept": "application/json, text/event-stream",
             "User-Agent": "my-agent/1.0"})
with urllib.request.urlopen(req) as r:
    print(json.load(r)["result"]["structuredContent"])

The User-Agent header in this example is required. The hosting service answers HTTP 403 (Cloudflare error 1010) to every request whose User-Agent starts with Python-urllib, the default of the Python standard library, or with libwww-perl, on the MCP server, the static API and llms.txt alike. The MCP Python SDK, requests, httpx, curl and browsers send other User-Agents and need no change.

Tools

All tools are read-only and return figures with units, methods and source ids.

search_companies

Companies by name, ticker, SEC CIK or id, with a country filter.

get_statement

Figures of one statement with units, methods and source ids, for a range of fiscal years, quarters or dates.

get_ratios

Ratio values with formula ids, units and the snapshot figures each value was computed from.

get_snapshot_info

Coverage, conventions, the validation summary, statements, files and the citation format.

get_sources

Source documents with URL, release or filing date and SHA-256.

Static API

Plain files behind a cache of 5 minutes, with cross-origin access allowed.

Latest Snapshot of a Company

curl https://annalist-fin.pages.dev/api/v1/companies/apple/latest.json

One Statement

https://annalist-fin.pages.dev/api/v1/companies/{company}/snapshots/{snapshot}/statements/pl_quarterly.json

Ratios of One Frequency

https://annalist-fin.pages.dev/api/v1/companies/{company}/snapshots/{snapshot}/ratios/ttm.json

Citation

Each figure should be cited with its snapshot and its source document.

Annalist, {company name}, snapshot {company id}/{snapshot id} (as of {period}); {item label}, {period}; source {document id} ({document url})