Metadata-Version: 2.5
Name: avanza-mcp
Version: 2.1.0
Summary: MCP server for Avanza public market data API - Swedish stocks, funds, and more
License-File: LICENSE.md
Requires-Python: >=3.12
Requires-Dist: fastmcp==3.4.7
Requires-Dist: httpx-sse>=0.4.3
Requires-Dist: httpx<1.0,>=0.28.1
Requires-Dist: keyring<26.0,>=25.7
Requires-Dist: pydantic>=2.0.0
Requires-Dist: qrcode<9.0,>=8.2
Requires-Dist: tenacity>=9.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Description-Content-Type: text/markdown

# Avanza MCP Server

![PyPI - Version](https://img.shields.io/pypi/v/avanza-mcp)
[![CI](https://github.com/AnteWall/avanza-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/AnteWall/avanza-mcp/actions/workflows/ci.yml)

Read-only access to Avanza market and optional account data from your MCP client. Public tools require no Avanza account.

## Disclaimer

This is an unofficial API client/MCP Server. Not affiliated with Avanza Bank AB. The underlying API can be taken down or changed without warning at any point in time.

The author of this software is not responsible for any indirect damages (foreseeable or unforeseeable), such as, if necessary, loss or alteration of or fraudulent access to data, accidental transmission of viruses or of any other harmful element, loss of profits or opportunities, the cost of replacement goods and services or the attitude and behavior of a third party.

## Features

- Stocks, funds, ETFs, certificates, warrants and futures/forwards.
- Quotes, charts, financial ratios, dividends, order books and ownership data.
- Fund performance, fees, holdings, sustainability and research prompts.
- Optional local BankID authentication for read-only accounts, holdings and activity.

## Setup

Requires [uv](https://docs.astral.sh/uv/) and Python 3.12+. Local clients launch the server over stdio.

<details>
<summary>Claude Desktop and Cursor</summary>

Both use this configuration:

```json
{
  "mcpServers": {
    "avanza": {
      "command": "uvx",
      "args": ["avanza-mcp"]
    }
  }
}
```

- **Claude Desktop:** open Settings > Developer > Edit Config, merge the configuration, then fully restart Claude Desktop.
- **Cursor:** add it to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` globally. Enable the server in Cursor's MCP settings.

</details>

<details>
<summary>Claude Code</summary>

Run in your project:

```bash
claude mcp add avanza -- uvx avanza-mcp
```

Use `/mcp` in Claude Code to check the connection.

</details>

<details>
<summary>Visual Studio Code</summary>

Add to `.vscode/mcp.json`, or open **MCP: Open User Configuration** for global setup:

```json
{
  "servers": {
    "avanza": {
      "type": "stdio",
      "command": "uvx",
      "args": ["avanza-mcp"]
    }
  }
}
```

Run **MCP: List Servers**, start `avanza`, and enable its tools in agent chat.

</details>

<details>
<summary>OpenCode</summary>

Add to your project's `opencode.json` or global `~/.config/opencode/opencode.json`:

```json
{
  "mcp": {
    "avanza": {
      "type": "local",
      "command": ["uvx", "avanza-mcp"],
      "enabled": true
    }
  }
}
```

</details>

<details>
<summary>HTTP and ChatGPT</summary>

From a source checkout:

```bash
uv sync
uv run fastmcp run src/avanza_mcp/__init__.py:mcp --transport http
```

Connect HTTP clients to `http://localhost:8000/mcp`. ChatGPT requires a remotely reachable HTTPS deployment; add its `/mcp` URL using [ChatGPT's developer-mode setup](https://platform.openai.com/docs/guides/developer-mode).

This project does not provide a hosted endpoint. Configure access controls before exposing your server publicly.

</details>

<details>
<summary>Python</summary>

Install with `uv add avanza-mcp`, then use FastMCP's in-process client:

```python
import asyncio
from fastmcp import Client
from avanza_mcp import mcp

async def main():
    async with Client(mcp) as client:
        result = await client.call_tool(
            "search_instruments", {"query": "Volvo", "instrument_type": "stock"}
        )
        print(result.structured_content)

asyncio.run(main())
```

</details>

If a desktop client cannot find `uvx`, use its absolute executable path. See [DEVELOPMENT.md](DEVELOPMENT.md) for running from source and tests.

## Experimental Account Access

> [!WARNING]
> BankID authentication and account tools are experimental and rely on undocumented Avanza APIs that may change without notice. Review the privacy notes below before enabling them.

Authenticated access is disabled by default. Enable it by adding `AVANZA_MCP_AUTH=1` to the local MCP server environment. For example, OpenCode uses:

```json
{
  "mcp": {
    "avanza": {
      "type": "local",
      "command": ["uvx", "avanza-mcp"],
      "environment": {"AVANZA_MCP_AUTH": "1"},
      "enabled": true
    }
  }
}
```

Restart OpenCode after changing its configuration.

### Authentication Flow

1. A temporary page opens on `127.0.0.1` and asks for consent.
2. After approval, scan the locally rendered QR code with BankID.
3. Avanza verifies the session and enables the experimental tools.

No Avanza password is requested in the browser or chat. Existing market-data tools automatically use the valid session when one is available; no duplicate authenticated market tools are added.

### Session Data

Verified session cookies and the Avanza security token are stored in the operating system's native credential store and revalidated on startup:

- macOS Keychain
- Windows Credential Manager
- Linux Secret Service, which must be installed, unlocked and available over D-Bus

Credentials are not stored in project files, browser storage, logs, or MCP results. Account responses are not cached by this project.

Avanza controls session duration through the account's website setting. See [How long can I stay logged in?](https://www.avanza.se/kundservice.html/5121/hur-lange-kan-jag-vara-inloggad-pa-mitt-konto-utan-att-loggas-ut) to change it.

Use `disconnect_avanza` to remove the local credential and attempt remote logout.

Account tool results may be sent to the configured model provider and saved in conversation history.

## Tools

The default 34-tool catalog is read-only. Search first to obtain an `order_book_id`; history tools expose pagination. Data is latest available, not guaranteed live.

| Category | Tool | Description |
|----------|------|-------------|
| Search | `search_instruments` | Find instruments by name, ticker or ISIN |
| Search | `get_instrument_by_order_book_id` | Match an exact ID within search candidates |
| Stocks | `get_stock_info` | Company, listing, fundamentals and quote |
| Stocks | `get_stock_quote` | Latest price and trading volume |
| Stocks | `get_stock_chart` | Historical OHLC price points |
| Stocks | `get_stock_analysis` | A named financial-ratio history |
| Stocks | `get_dividends` | A named dividend metric by financial year |
| Stocks | `get_company_financials` | A named annual or quarterly financial metric |
| Market | `get_orderbook` | Bid/ask depth |
| Market | `get_marketplace_info` | Trading hours and market status |
| Market | `get_recent_trades` | Recent trade snapshot |
| Market | `get_broker_trade_summary` | Broker buy/sell activity |
| Funds | `get_fund_info` | NAV, performance, fees and fund information |
| Funds | `get_fund_sustainability` | ESG and sustainability metrics |
| Funds | `get_fund_chart` | Historical fund chart points |
| Funds | `get_fund_chart_periods` | Available performance periods |
| Funds | `get_fund_description` | Investment strategy and category |
| Funds | `get_fund_holdings` | Country, sector and top-holding allocations |
| Certificates | `filter_certificates` | Filter and list certificates |
| Certificates | `get_certificate_info` | Certificate information |
| Certificates | `get_certificate_details` | Extended certificate details |
| Warrants | `filter_warrants` | Filter and list warrants |
| Warrants | `get_warrant_info` | Warrant information |
| Warrants | `get_warrant_details` | Extended warrant details |
| ETFs | `filter_etfs` | Filter and list ETFs |
| ETFs | `get_etf_info` | ETF information |
| ETFs | `get_etf_details` | Extended ETF details |
| Futures/Forwards | `list_futures_forwards` | Filter and list contracts |
| Futures/Forwards | `get_future_forward_filter_options` | Available contract filters |
| Futures/Forwards | `get_future_forward_info` | Contract information |
| Futures/Forwards | `get_future_forward_details` | Extended contract details |
| Additional | `get_number_of_owners` | Avanza ownership history |
| Additional | `get_short_selling` | Short-selling history |
| Additional | `get_marketmaker_chart` | Traded-product OHLC and market-maker data |

### Experimental Auth Tools

These tools are available only when experimental account access is enabled. Data access is read-only; no tool places, edits, or cancels orders.

| Category | Tool | Description |
|----------|------|-------------|
| Session | `connect_avanza` | Open the local consent and BankID flow |
| Session | `disconnect_avanza` | Confirm disconnection and remove the saved session |
| Session | `get_auth_status` | Check the safe local connection state |
| Accounts | `get_accounts` | Account identities, balances and values |
| Accounts | `get_holdings` | Current positions and cash balances |
| Accounts | `get_transactions` | Bounded transaction history |
| Accounts | `get_credit_info` | Credit, collateral and leverage figures |
| Portfolio | `get_portfolio_insights` | Aggregate portfolio development |
| Activity | `get_active_orders` | Current orders without modification controls |
| Activity | `get_deals` | Current executed deals |
| Activity | `get_stop_loss_orders` | Current stop-loss orders without modification controls |
| Saved Data | `get_watchlists` | Saved watchlists and order-book IDs |
| Saved Data | `get_price_alerts` | Price alerts for an order book |
| Saved Data | `get_current_offers` | Current customer offers |
| Research | `get_instrument_news` | Bounded instrument news |
| Research | `get_forum_posts` | Bounded forum posts as untrusted text |
| Research | `get_insider_transactions` | Reported insider transactions |

## Prompts

- `analyze_stock(stock_symbol)` - Research a stock's fundamentals and price history.
- `compare_funds(fund_names)` - Compare two or more supplied funds.
- `screen_dividend_stocks(candidates, min_yield=3.0)` - Screen supplied stocks by dividend yield.

## Resources

- `avanza://docs/usage` - Tool usage guide.
- `avanza://docs/quick-start` - Common workflows.
- `avanza://stock/{order_book_id}` - Stock summary as Markdown.
- `avanza://fund/{order_book_id}` - Fund summary as Markdown.

## License

[MIT](LICENSE.md)
