Avanza-MCP

Single-script CLI + Textual TUI for Avanza portfolio monitoring, regular buy/sell orders, stop-loss management, MCP integration, and paper trading.

Trading-assistant context lives in:

• INSTRUCTIONS/INSTRUCTIONS.md: standing operating rules and safety constraints.

• INSTRUCTIONS/MEMORY.md: timestamped lessons, mistakes, strategy updates, and checklist changes. This is historical context, not live portfolio state.

• INSTRUCTIONS/WARMUP.md: prompt for starting a fresh Codex trading session with the right context.

The INSTRUCTIONS/ folder is kept visible in git, but its private contents are ignored and should remain local-only.

For trading analysis, always refresh live Avanza MCP data. Do not treat markdown memory as current holdings, orders, prices, account IDs, or stop-loss IDs.

Credentials are prompted at runtime:

• username: visible prompt, unless passed with --username

• password: masked

• current TOTP code: masked

Alternatively, pass --onepassword-item ITEM and optional --onepassword-vault VAULT to read the Avanza username, password, and current TOTP code through the 1Password CLI (op). The TUI has a matching Login with 1Password path. The tool does not store these secrets; op will ask you to authorize access through the local 1Password app.

The current TOTP code is passed to avanza-api as totpToken, which is the field name expected by the installed library version.

TUI Demo:

Setup

uv sync --dev
chmod +x scripts/verify.sh .githooks/pre-commit .githooks/pre-push
git config core.hooksPath .githooks

If uv is not installed yet, install it first:

curl -LsSf https://astral.sh/uv/install.sh | sh

Command examples below can be run either inside an activated environment or by prefixing with uv run. For example: uv run python avanza_cli.py tui.

Run the full quality gate at any time:

scripts/verify.sh

Related MCP server: Angel One Mcp

Commands

Console commands print human-readable Rich tables and summaries, not raw API payloads.

Show running app version:

python avanza_cli.py --version

Show account overview:

python avanza_cli.py accounts

Show portfolio summary:

python avanza_cli.py portfolio summary

Show detailed portfolio positions:

python avanza_cli.py portfolio positions

Show transaction history (executed orders by default):

python avanza_cli.py transactions list

Pull broader history:

python avanza_cli.py transactions list --all --max-elements 5000

Search for a stock/order book:

python avanza_cli.py search-stock "VOLV B"

List active stop-loss orders:

python avanza_cli.py stoploss list

Dry-run a trailing/gliding sell stop-loss:

python avanza_cli.py stoploss set \
  --account-id ACCOUNT_ID \
  --order-book-id ORDER_BOOK_ID \
  --trigger-type follow-upwards \
  --trigger-value 5 \
  --trigger-value-type % \
  --order-type sell \
  --order-price 1 \
  --order-price-type % \
  --volume 10

Place the order for real by adding --confirm after reviewing the dry-run output. If --valid-until is omitted, avanza_cli automatically uses the longest currently allowed date (today + 90 days). If --order-valid-days is omitted, avanza_cli uses the current Avanza-safe default (1). Dry-run/preview now shows both trigger validity and derived triggered-order expiry (if triggered today). For live non-SEK/foreign instruments, order_valid_days > 1 is blocked to prevent Avanza Ogiltigt giltighetsdatum trigger failures.

Delete a stop-loss order dry-run:

python avanza_cli.py stoploss delete \
  --account-id ACCOUNT_ID \
  --stop-loss-id STOP_LOSS_ID

Delete for real by adding --confirm.

List open regular orders:

python avanza_cli.py orders list

Dry-run a regular buy/sell order:

python avanza_cli.py orders set \
  --account-id ACCOUNT_ID \
  --order-book-id ORDER_BOOK_ID \
  --order-type buy \
  --price 100 \
  --valid-until 2026-05-28 \
  --volume 10 \
  --condition normal

Delete an order dry-run:

python avanza_cli.py orders delete \
  --account-id ACCOUNT_ID \
  --order-id ORDER_ID

Textual TUI

Run the terminal UI from the same script:

python avanza_cli.py tui

The TUI masks password and TOTP inputs, clears those fields after a successful login, and hides the login screen. You can also enter a 1Password item name/ID and optional vault, then use Login with 1Password to let the local op CLI fetch username, password, and TOTP after your 1Password approval. Use Review Only first to validate and log an order request without creating a paper or live order.

Use the Reload TUI top-button to hard-restart python avanza_cli.py tui with the same arguments and load latest code changes without manually quitting/relaunching. The bottom status bar includes an automatic GitHub update checker indicator; when a newer release exists, it flashes a warning status. Controls: AVANZA_UPDATE_CHECK_ENABLED=0 disables checks, AVANZA_GITHUB_REPO=owner/repo overrides source.

After login, the largest account by total value is selected by default. The top panel groups account metrics into colored cards, keeps action buttons together, and shows a live clock plus a weekday OMXS open/close countdown. The P/L metric cycles through 1D P/L, 1W P/L, 1M P/L, 1Y P/L, Since Start P/L, and Total P/L, with SEK and % values colored separately. The main table shows the selected account's stocks with day movement, profit state, a distinct header row, and a real-time quote indicator: green dot for real-time, yellow dot for delayed or unresolved status. The order ticket searches as you type by stock name, ticker, or ISIN, so it supports opening new positions as well as trading current holdings. The lower table shows stop-losses and open orders for the selected account, with trigger and price values labeled as SEK or %; its cancel column opens a guarded cancellation ticket. Buy/sell side cells are color-coded green/red. Click any table column header to sort by that column; click the same header again to reverse the order. Drag the horizontal divider between tables, the vertical divider beside Active Trades, or the left edge of the order/stop-loss ticket to resize panes. Position and order state refreshes live every 5 seconds.

Multi-session mode: use Login extra account to add more authenticated Avanza sessions without leaving TUI. The session selector lets you switch tenant context quickly; account drop-down and all tables follow the selected session. Background refresh keeps inactive tenant/account snapshots warm without visibly switching the active TUI context.

MCP Server Registration & Run

This project exposes MCP through python avanza_cli.py mcp (stdio transport).

1) Start and authenticate the TUI

python avanza_cli.py tui

Log in, then enable the MCP tick box in the TUI. This starts the localhost bridge and writes .avanza_mcp_session.json. By default, the MCP bridge token is saved to macOS Keychain (security CLI) and only metadata is written to the dotfile; if keychain is unavailable, it falls back to file storage. Override with AVANZA_MCP_SESSION_BACKEND=keychain|file|auto (default auto).

2) Register the MCP server in Codex/Codex CLI

Add this to ~/.codex/config.toml:

[mcp_servers.avanza-mcp]
command = "python"
args = ["/ABSOLUTE/PATH/TO/avanza_cli.py", "mcp"]

Use the absolute path to your local avanza_cli.py.

3) Run from your MCP client

After registration, start/reload Codex or Codex CLI. It will launch:

python avanza_cli.py mcp

The MCP proxy forwards tool calls to the authenticated TUI session through the localhost bridge. MCP starts read-only. Enable Live R/W in the TUI for live mutations; live stop-loss/order placement, edit, or deletion still requires MCP arguments to include confirm: true. MCP activity is shown in the lower-right log console.

For multi-session setups:

• use avanza_sessions to inspect loaded tenant sessions,

• use avanza_select_session to switch active context,

• account/session-context avanza_* tools accept optional tenant_session_id for explicit tenant routing.

• or pass account_id and the bridge auto-scopes to the session owning that account.

• paper-ledger tools use session_id for paper ledger grouping; use tenant_session_id when explicit tenant routing is required.

Available MCP Tools

Canonical naming note:

• use avanza_open_orders

• use avanza_stoplosses

TradingView/Zacks scrape mode notes

• These tools are intentionally marked experimental.

• tv_scrape_* runs in free anonymous mode.

• tv_auth_* supports three auth paths:

  • explicit tool input (cookie or sessionid + sessionid_sign),

  • environment variables (TRADINGVIEW_SESSIONID, optional TRADINGVIEW_SESSIONID_SIGN),

  • saved local session via tv_auth_session_set.

• Saved TradingView session storage defaults to macOS Keychain (security CLI) when available, with metadata in .avanza_tradingview_session.json (ignored by git). Fallback is file-only storage.

• Optional override: AVANZA_TV_SESSION_BACKEND=keychain|file|auto (default auto).

• Preferred path: tv_auth_session_login_auto to open an instrumented browser and capture cookies automatically after login.

• Browser-assisted flow:

  1. call tv_auth_session_login_auto,

  2. log in normally in opened browser window,

  3. wait for auto-capture confirmation, then run tv_auth_session_status,

  4. use tv_auth_* tools with no repeated cookie input.

• The TUI TradingView Lists tab uses the same authenticated profile and provides a dedicated custom-list monitor with list switching.

• If auto mode is unavailable, fallback is tv_auth_session_start + manual tv_auth_session_set.

• If Codex or another agent does not expose tv_* tools as direct native calls, keep using the registered avanza_cli MCP server and call the tools through the local stdio/TUI bridge. The bridge command remains python avanza_cli.py mcp; it forwards to the authenticated TUI localhost session.

• Pre-open workflow:

  1. start and authenticate the TUI, then enable MCP,

  2. confirm tv_auth_session_status if authenticated TradingView data is needed,

  3. call tv_preopen_batch_snapshot for watchlist/candidate symbols or avanza_tv_preopen_portfolio_bundle for an Avanza account review,

  4. use tv_scrape_heatmap with filters such as exchanges=["NASDAQ","NYSE","AMEX"], exclude_otc=true, min_market_cap, min_price, and min_volume to avoid OTC/microcap noise.

• Performance notes: tv_preopen_batch_snapshot uses a bulk TradingView scanner call for normal multi-symbol reviews; Avanza MCP read tools keep a short in-process account cache to avoid repeated full portfolio/stop/order pulls during focused workflows; avanza_orderbook_quotes deduplicates IDs and can skip metadata enrichment when fields contains only price fields.

• TradingView extended-hours fields depend on TradingView entitlement/session and scanner availability. premarket_close, postmarket_close, update_mode, and quote freshness warnings are reported explicitly; missing fields are returned as null instead of inferred from Avanza.

• zacks_scrape_symbol is best effort; it now attempts the quote page and free Zacks equity-report page, returning analysis_summary, analysis_sources, and blocked_sources when available. Zacks can return bot-protection pages unless a valid browser session/cookie is provided.

• Treat scrape output as decision support only. Keep live mutations behind Avanza read/write + explicit confirm: true.

• API-key tools:

  • fmp_analyst_recommendations: pass api_key or set FMP_API_KEY.

  • polygon_analyst_insights: pass api_key or set POLYGON_API_KEY.

MCP Transaction History Quick Use

Use avanza_transactions to retrieve executed order history (BUY/SELL by default).

• Most recent 15 rows:

  • {"max_elements": 15}

• Include dividends and interest:

  • {"types": ["BUY", "SELL", "DIVIDEND", "INTEREST"], "max_elements": 200}

• Full export window:

  • {"transactions_from": "2026-01-01", "transactions_to": "2026-12-31", "executed_only": false, "max_elements": 5000}

avanza_transactions is read-only and works while MCP remains read-only.

4) ChatGPT desktop note

ChatGPT developer mode currently expects remote MCP apps/connectors over SSE or streaming HTTP, so it cannot directly register this local stdio proxy.

For auto-trading experiments, use avanza_live_snapshot as the polling tool. It returns a decision-ready account snapshot and is safe to call every 5 seconds. Paper trading is available in read-only MCP mode through avanza_paper_stoploss_set, avanza_paper_order_set, avanza_paper_orders, and avanza_paper_cancel; paper state is stored in .avanza_paper_session.json and never places an Avanza order. The TUI's Paper tick box is on by default; while it is on, the order and stop-loss form submit buttons create local paper orders. Turn Paper off only when you intend to use live Avanza placement, which still requires typing PLACE. Regular live buy/sell orders are also exposed through avanza_order_set and avanza_order_delete, gated by MCP R/W mode and confirm: true.

TUI sessions write structured JSONL logs under avanza-cli/logs/: a timestamped session log plus persistent app.jsonl, mcp.jsonl, and trading.jsonl.

Safety

This uses the unofficial avanza-api package. Start with stoploss list and dry-runs. Verify Avanza's live interpretation of % and gliding stop-loss fields with very small size before trusting it for meaningful orders.

Stop-losses are not guaranteed earnings-gap or overnight protection. A tight Kurs 99% can avoid a bad normal-session fill, but it can also fail, remain unfilled, or show ERROR if price gaps through the trigger after hours, before open, during a halt, or in a fast market. Treat ERROR rows as unprotected, and handle after-close/before-open catalysts with explicit sizing, trim, sell, hedge, or hold-and-accept decisions.

If an ERROR row reason contains Ogiltigt giltighetsdatum, the failure is usually triggered-order validity, not trigger logic or slippage. Set order_valid_days=1 and replace the stop-loss.

Credits

Creators: Hamid Kashfi and Codex (OpenAI).

This project builds on the Python avanza-api library by fama93:

• PyPI: avanza-api

• Source: github.com/fhqvst/avanza