AlphaDesk — dense, fast market-research terminal & MCP integration platform

A dense, fast market-research terminal and integration platform. Readers connect their own market-data and news providers; AlphaDesk is the workspace that connects, checks and presents what those providers — and the public record at SEC EDGAR and the US Treasury — actually say. Questions are asked in the reader's own AI agent (Claude, ChatGPT, Codex, Cursor, opencode), which reads the same records through 50 read-only agent tools (MCP).

AlphaDesk reads: quotes and charts, news, SEC filings, financial statements, ownership and insider activity, earnings and corporate calendars, options, crypto. It does not trade, route orders, hold positions, score ideas or write summaries.

Two ways to use it — the managed cloud or your own server. The code is open source under the GNU AGPL-3.0, with a commercial licence for anyone who cannot meet its terms. See Licence.

Figures in every screenshot are blurred on purpose: they came from a reader's own vendor keys, and vendors restrict public display of their data. The layout is the real thing.

Chart — your own SVG engine, session bands, drawings	Earnings week — dated by the company's own release and its SEC filing
News — your feeds in one three-day window, searched by word or meaning	Options — chains by expiry, calls and puts either side of the price

---

Contents

1. What AlphaDesk is — and is not
2. Two ways to run it
3. Design principles
4. Features
5. Data sources
6. Search
7. Agent access (MCP)
8. Accounts, security and privacy
9. Architecture
10. Repository layout
11. Development
12. Configuration reference
13. Production deployment and operations
14. Testing and quality
15. Known limitations
16. History
17. Licence

---

What AlphaDesk is — and is not

AlphaDesk is	AlphaDesk is not
A consumption terminal: it fetches, checks and presents market information	A trading system — there is no order routing, position state or broker integration
An integration platform: every vendor figure runs on the reader's own key	An aggregator — the server holds no vendor keys and never shares one reader's data with another
A presenter of records: filings, statements, stories and prices, shown whole with their source	A summariser — no model writes, paraphrases or scores anything here
Pluggable: news feeds, market data, transcripts and dashboard tiles are swappable providers	A black box — every list is chronological, alphabetical or ordered by the figure it shows

It is offered free at present (payments are designed but switched off; see Accounts).

---

Two ways to run it

	Option A — Managed cloud	Option B — Self-hosted
Price	Free during early access. Planned: $19 a month or $190 a year, announced before it starts	Free
Licence	Commercial terms of service — no AGPL obligations for you	GNU AGPL-3.0
You run	Nothing: sign in with GitHub	One container or one Python process, and a database
Search by meaning	Included (the embedding model runs on our servers)	Runs on your CPU (~1.2 GB model, 2 vCPU / 4 GiB recommended) or switched off
Vendor keys	Your own, connected on the Account page	Your own, in .env or the Account page
Updates	Continuous	git pull and restart

Option A — Managed cloud

1. Open the hosted terminal and sign in with GitHub — the account is created on first sign-in. (Google sign-in admits invited accounts only until Google approves the app.)
2. On the Account page, connect the market-data and news providers you already use (Alpaca, FMP, Finnhub, Polygon, CoinGecko, Tiingo, …). SEC EDGAR and the US Treasury need no key.
3. It is free during early access — there is no plan to choose and no card to enter. Paid plans ($19 a month or $190 a year, each after a 14-day trial) will be announced to account holders before they start; nobody is charged without subscribing.
4. Optional: connect your own agent from the Account page — a token for Claude Code, Codex, Cursor or opencode, or add the server URL as a connector in Claude.ai or ChatGPT.

Option B — Self-hosted (AGPL-3.0)

You need a SEC User-Agent with real contact details (SEC blocks requests without one), Python 3.11+ or Docker, and — for anything beyond EDGAR and Treasury data — your own vendor keys.

1. Configure. Copy the template and fill in the two required values:

cp alphadesk/deploy/env.example .env

Setting in .env	Required	What to put
ALPHADESK_VAULT_KEY	yes	32 random bytes, base64 — seals stored vendor keys; keep a copy, losing it makes them unreadable
SEC_USER_AGENT	yes	AlphaDesk (you@example.com) — a name and a real email
ALPHADESK_AUTH	for one person	off: a single local account with no sign-in
ALPHADESK_DATABASE_URL	no	a postgres:// URL; unset, SQLite in ALPHADESK_DATA (~/.alphadesk)
ALPACA_API_KEY, ALPACA_SECRET_KEY, FMP_API_KEY, FINNHUB_API_KEY, POLYGON_API_KEY, ALPHAVANTAGE_API_KEY, COINGECKO_API_KEY	no	your own keys; sealed into the local account with python -m alphadesk.main keys import-env (or connect them on the Account page instead)
ALPHADESK_SEMANTIC_SEARCH	no	off skips the ~1.2 GB embedding model; search then matches words only
GOOGLE_CLIENT_ID / GITHUB_CLIENT_ID (+ secrets), ALPHADESK_BASE_URL	for several people	single sign-on for a shared instance

Generate the vault key with:

python -c "import os, base64; print(base64.b64encode(os.urandom(32)).decode())"

2a. Install from PyPI — the shortest route; the built interface ships with the package:

pip install alphadesk

python -m alphadesk.main dashboard

The terminal is at http://127.0.0.1:8000. The first start downloads the embedding model into the Hugging Face cache (skip it with ALPHADESK_SEMANTIC_SEARCH=off).

2b. Or run from a clone, which is what you want if you intend to change anything:

pip install -r requirements.txt
python -m alphadesk.main keys import-env
python -m alphadesk.main dashboard

2c. Or run with Docker. The image bakes the embedding model in, so a container downloads nothing at start:

docker build -t alphadesk .

docker run -d --name alphadesk -p 8000:8000 --env-file .env -e ALPHADESK_DATA=/data -v alphadesk-data:/data alphadesk

With ALPHADESK_AUTH left on and no sign-on provider configured, create a password account inside the container:

docker exec -it alphadesk python -m alphadesk.main user add you@example.com

3. Keep it private or publish your changes. Under the AGPL, if you let other people use a modified copy over a network, you must offer them the source of your version. Using it yourself, unmodified, or keeping your changes to yourself on your own machine carries no such obligation. Billing stays off (ALPHADESK_BILLING_ENFORCE is off by default), so every account on your instance has full access.

---

Design principles

These are the product. Much of what might look missing was built, measured and removed on purpose — DECISIONS.md says what and why. Bring evidence and open an issue.

1. Nothing is paraphrased. Every panel and agent tool returns what a vendor or EDGAR actually said — a filing in pages, a statement series, a story's own text. If a figure cannot be shown with its source, it is not shown.
2. Indicators hide when the data cannot support them. Bar coverage and gap size are measured per series; below the floor RSI and MACD are hidden rather than drawn over sparse prints that would render identically to a liquid name's chart.
3. Nothing is ranked for you. The screener window is alphabetical; calendars and agent tools order only by the figure on each row. Search results are newest first — a model may decide what is related, never what comes first.
4. An idle terminal spends nothing. Background loops fetch only public data and each reader's own news; everything else is fetched on request, on the requesting reader's keys.
5. Untrusted text stays untrusted. Headlines, articles, filings and transcripts are data. Nothing here acts on them, and the agent tools that return them say so.
6. Not an aggregator. Merging several news feeds is the reader's act, on their own credentials, for their own window.
7. The agent surface is read-only and per reader. Every agent call runs as exactly the reader whose token or grant it carries.
8. Vendor data is the reader's. No vendor key on the server; no keyless route to a commercial vendor or unofficial endpoint; every vendor cache keyed by reader; vendor data kept only as long as a feature reads it.

---

Features

Pages

Page	What it shows
Landing (/)	Product overview with blurred screenshots; sign-in and sign-up
Markets	A composable board: chart, equity overview, funds built on the stock, stock/ETF/crypto/currency/option movers, Treasury yields, heatmap, news. Stock and ETF movers step back to a past session, computed from the whole market that day against the session before it
Chart	Full workspace: candles, line, area, step and other styles; 1-minute to multi-year intervals; indicators and templates; drawing tools (desktop, per visit); multi-chart layouts; overnight, pre-market, after-hours and weekend session shading
Analysis	One name end to end: chart, filings, price performance, key statistics, earnings history and consensus, analysts, rating changes, financials as filed, splits, dividends, institutional and insider ownership, news. Funds add holdings and breakdown; coins get their CoinGecko record instead of stock-only panels
Profile	Who a company is: EDGAR registrant facts, the latest 10-K/20-F business and properties sections verbatim, locations, officers; a coin's CoinGecko record
News	Each reader's merged feeds, three days deep, newest first; filter by words, source or board; search by words and by meaning; an in-page reader with full text where the feed carries it
Earnings	The week's reporters, dated by the company's own release and joined to its SEC results filing; sessions predicted from history; estimates, actuals, surprise, market cap, volatility, liquidity
Calendars	Economic releases, dividends, corroborated splits and IPOs
Options	Chains with implied volatility, calls green and puts red; options flow seen live
Sectors	Sector funds by weight and dollars traded, with breadth
Baskets	36 curated baskets grouped by the news that moves them (rates, oil, tariffs, chip export rules, bitcoin, …), plus the reader's own
Portfolio / custom views	The reader's saved boards
Account	Coverage matrix of connected vendors and feeds, agent access (tokens and connected apps), sign-in methods and sessions
Admin	Owners only: accounts, last seen, sign-in methods, sign-out-everywhere, disable, delete
Terms, Privacy, Disclaimer	Public drafts pending legal review

Across the terminal

• The symbol strip scopes every page; picking a row adds and selects the symbol without moving the page.
• Composable boards: show, hide, reorder, size and place tiles; the layout lives in the URL, so a link restores the exact board.
• Live data where the reader's plan streams it (Alpaca stock, crypto and news sockets), polling elsewhere; a 428 prompt names the vendors and plans that would fill any panel the reader's keys cannot.
• Phones: every page is laid out for a 375-pixel screen as well as a desktop.
• Light and dark themes, a hand-rolled design system on a 4-pixel grid with six type roles, and full keyboard focus handling in every overlay.

---

Data sources

Market data — the reader's own keys

Vendor	Carries (plan-dependent)
Alpaca	Consolidated (SIP) and IEX bars, overnight (Blue Ocean) session, quotes, movers, crypto, option chains with IV, options flow, corporate actions
Financial Modeling Prep	Calendars (earnings, economic, dividends, splits, IPOs), key statistics, profiles, analysts, market caps, currencies, press releases, fund data
Polygon (Massive)	Bars, quotes, movers, currencies, options
Finnhub	Company metrics, profiles, earnings calendar and sessions
Alpha Vantage	Company overview, bars
CoinGecko	Worldwide crypto prices, volume, market caps and coin records

For each panel the reader's connected vendors are asked in a fixed, documented order; the first that carries the figure answers. Charts and option chains are pinned to one vendor, never stitched across tapes.

News — the reader's own feeds

Alpaca (Benzinga), Polygon, Finnhub, Benzinga, Tiingo, Alpha Vantage, Marketaux and FMP. Several feeds merge into one window per reader, de-duplicated by URL. Alpaca's news streams live; the rest poll every five minutes.

A feed whose terms forbid keeping what it sends is not kept: Tiingo's Starter and trial plans may not have their data written to durable storage, so a key declared as one has its stories fetched and dropped, and the Account page says "Not kept" rather than showing a feed that polls and produces nothing.

Sources with no key — read, not licensed

Three sources need no key because there is nothing to buy: the reader turns each on with a button on the Account page.

Source	Carries
Nasdaq	Earnings, dividend, split and listing calendars — and today's trading halts, which no vendor in the catalogue carries at all
Yahoo	Charts, quotes and daily history from the public chart endpoint
Social	A mirror of one public account's posts

Two rules keep them honest. A keyed vendor is always asked first — every licensed vendor is ordered ahead of every scraped one, so a scraped source answers only where none does. And provenance travels with the answer: the catalogue marks the source unofficial, each payload carries it, the tile subtitle reads "scraped", and the data_sources agent tool resolves any vendor name back to licensed-or-read. The marker protects the reader's reasoning; it is not consent from the site.

No ticker is ever read out of a social post: a ticker inside a post is the author's claim, and attaching it would route an unverified assertion into that symbol's context.

Public data — no key

• SEC EDGAR: filings and their text, XBRL financial statements, Form 4 insider trades, 8-K Item 2.02 and 6-K results releases (release day read from the filing itself), ticker and company lists.
• US Treasury: the daily par yield curve.

Every source, how it is collected and its terms are listed in docs/data-sources.md. Vendor terms are separate from the code licence; see Known limitations.

---

Search

News search works two ways at once, everywhere a reader searches — the News filter box, "Search all" and the agent's news_search tool:

• By words — one rule shared by the server and the browser: whole words in order, plurals matched to singulars, a capitalised ticker matched exactly, and a query that names a company also finds stories tagged with it ("robinhood" finds stories tagged HOOD).

• By meaning — stories whose headline is close in meaning to the query are added and marked related, so "AI data center spending" finds "Equinix plans $5B–$7B annual data center buildout" without a shared phrase. This uses Qwen3-Embedding-0.6B (Apache 2.0), self-hosted inside the server: no text leaves AlphaDesk and there is no model key. Headlines are embedded once as they arrive; the threshold (cosine 0.50) was calibrated so that only on-topic stories are added. Results remain newest first.

  The embedding work never competes with the site: the model runs on a single CPU thread, the background worker runs at the lowest operating system priority, and it embeds only while no request is being served. Searches take about a third of a second.

A coin's news panel reads all crypto and what moves it — any coin's stories, crypto stocks, stories naming crypto, and Fed and rates headlines — each marked with the reason it is there.

---

Agent access (MCP)

AlphaDesk exposes the same records the interface shows as 50 read-only tools over the Model Context Protocol, at /api/agent/tools/mcp. Every call runs as the reader, on their keys, rate-limited to 120 requests a minute per token.

Connecting

• Claude.ai, ChatGPT — add a custom connector with the server address and sign in when asked (OAuth 2.1 with PKCE; one live grant per registered app).
• Claude Code, Codex, Cursor, opencode — create a token on the Account page under Agent access (shown once, stored hashed, revocable at once); the page gives each client's exact setup.

Tools

For	Tools
Today	market_today, market_tape, movers (stocks, ETFs, indices, crypto, currencies, options, bonds), sector_performance, sector_breadth
The reader's names	my_board, quotes, screener_window, baskets, find_symbol
One company	quote, key_stats, company_profile, fund_profile, analyst_view, financial_statements, earnings_history, ownership, insider_activity, peers, compare_metrics
Prices	price_history, price_chart
News	symbol_news, news_search, news_story
Filings and calls	list_filings, filing_text, transcripts, transcript_text
Calendars	earnings_calendar, recently_reported, economic_calendar, corporate_calendar
Options	option_expirations, option_chain, options_flow
What just happened	catalysts (filings, halts, government action and social posts on one tape), filing_feed, trading_halts, government_actions, social_posts
A past session	movers(session=…) for stocks and ETFs, with market_sessions for the days the market actually opened
Provenance	data_sources — whether a figure came from a licensed vendor or a scraped page

The tools are written for an agent that cannot see the screen: find_symbol resolves a name to a ticker from the SEC list rather than letting an agent guess; price_chart returns a thinned series carrying each point's RSI and MACD; filing_text and transcript_text return whole documents in pages; news_search marks each story as a word or meaning match. Tools that return publisher or filer text say that it is untrusted input. Every tool carries readOnlyHint, so a client can call them without asking permission for each read.

---

Accounts, security and privacy

• Sign-in: single sign-on is the only door and is also sign-up — Google and GitHub are live, Microsoft is a configuration slot. The email address is the account key across providers; each sign-in's method is recorded.
• Sessions: HMAC-signed cookie, 14-day lifetime, sign-out everywhere.
• Vendor keys: sealed per reader with AES-256-GCM under a master key held outside the database; never logged, never shown after entry.
• Agent credentials: tokens and OAuth codes stored as SHA-256 hashes; OAuth clients sealed; consent page signed, same-site and unframeable.
• Owners (configured by email) reach the Admin page; everyone else is a reader. Access is free: a trial is recorded but the access gate is off and no payment processor is configured.
• Retention — vendor data is kept only as long as a feature reads it: stories 7 days, full article text 72 hours, meaning vectors with their stories, company announcements 30 days past the report, the forecast log 120 days, release habits 3 days, press-release checks 24 hours. Removing a key deletes what that key fetched.
• Deletion: a reader can delete their account, confirmed by typing its email; every row keyed to it is removed in one transaction. The table list is checked against the schema by the test suite.
• No analytics, advertising or tracking.

The full account, session, key-vault and agent-credential design is in docs/hosted-mode.md.

---

Architecture

                       ┌──────────────────────────────────────────────┐
  Browser (React SPA) ─┤  FastAPI · one process · one port            │
  Reader's agent (MCP) ┤                                              │
                       │  /api/*  ── panels, composed per request     │
                       │  /api/agent/tools/mcp ── 50 read-only tools  │
                       │  OAuth 2.1 at the root (/authorize, /token…) │
                       │                                              │
                       │  Per-reader DataRouter ──► reader's vendors  │──► Alpaca · FMP · Polygon
                       │    (ordered per panel; 428 when none carry)  │    Finnhub · Alpha Vantage
                       │                                              │    CoinGecko
                       │  Background:                                 │
                       │    news poll (5 min) + held news sockets     │──► each reader's feeds
                       │    EDGAR results sweep (15 min, weekdays)    │──► SEC EDGAR
                       │    daily earnings forecast capture           │──► Treasury
                       │    embedding worker (search by meaning)      │
                       └──────────────┬───────────────────────────────┘
                                      │
                         Postgres (Cloud SQL) in production
                         SQLite (WAL) in development