avanza-mcp 1.0.0__tar.gz

avanza_mcp-1.0.0/.github/PUBLISHING.md

@@ -0,0 +1,58 @@
+# Publishing to PyPI
+
+## Setup (One-time)
+
+### 1. Configure PyPI Trusted Publishing
+
+1. Go to https://pypi.org/manage/account/publishing/
+2. Add a new publisher:
+   - **PyPI Project Name**: `avanza-mcp`
+   - **Owner**: `antewall`
+   - **Repository**: `avanza-mcp`
+   - **Workflow**: `publish.yml`
+   - **Environment**: `pypi`
+
+### 2. Create GitHub Environment
+
+1. Go to repository Settings → Environments
+2. Create environment: `pypi`
+
+## Publishing a Release
+
+```bash
+# Patch release (1.0.0 -> 1.0.1)
+just release-patch
+
+# Minor release (1.0.0 -> 1.1.0)
+just release-minor
+
+# Major release (1.0.0 -> 2.0.0)
+just release-major
+```
+
+This will:
+1. Bump `__version__` in `src/avanza_mcp/__init__.py`
+2. Commit changes
+3. Create and push git tag
+4. Trigger CI to build and publish to PyPI
+
+## Version Management
+
+Version is defined in **one place**: `src/avanza_mcp/__init__.py`
+
+```python
+__version__ = "1.0.0"
+```
+
+All other files read from this:
+- `pyproject.toml` uses dynamic versioning
+- `src/avanza_mcp/client/base.py` imports and uses `__version__`
+
+## CI Workflow
+
+GitHub Actions automatically:
+1. Installs uv
+2. Builds package with `uv build`
+3. Publishes to PyPI with `uv publish` (using trusted publishing)
+
+Monitor at: https://github.com/antewall/avanza-mcp/actions

avanza_mcp-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,40 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  test:
+    name: Test on Python ${{ matrix.python-version }}
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Verify imports
+        run: uv run python -c "from avanza_mcp import mcp; print('✓ Import successful')"
+
+      - name: Build package
+        run: uv build
+
+      - name: Check package
+        run: |
+          uv tool run twine check dist/*

avanza_mcp-1.0.0/.github/workflows/publish.yml

@@ -0,0 +1,34 @@
+name: Build and Publish to PyPI
+
+on:
+  push:
+    tags:
+      - 'v*'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  publish:
+    name: Build and publish to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/avanza-mcp
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        run: uv publish

avanza_mcp-1.0.0/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+.claude
+
+.env

avanza_mcp-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12

avanza_mcp-1.0.0/CLAUDE.md

@@ -0,0 +1,123 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Persona
+
+You are a senior Python developer with deep expertise in MCP (Model Context Protocol) and the FastMCP framework. You write clean, idiomatic Python code following modern best practices. You understand async patterns, type hints, and API design principles.
+
+## FastMCP Documentation
+
+For comprehensive FastMCP documentation, reference: https://gofastmcp.com/llms-full.txt
+
+Key FastMCP concepts:
+- **Tools**: Functions exposed to LLMs via `@mcp.tool` decorator
+- **Resources**: Data exposed via `@mcp.resource` decorator
+- **Prompts**: Reusable prompt templates via `@mcp.prompt` decorator
+- **Context**: Access request context via `Context` parameter for logging, progress, and state
+- **Client**: `fastmcp.Client` for connecting to MCP servers programmatically
+
+## Project Overview
+
+This is an MCP (Model Context Protocol) server for Avanza built with FastMCP 3.0.0b1 and Python 3.12. It provides 18 tools for accessing Swedish market data (stocks, funds) without authentication.
+
+## Commands
+
+```bash
+# Install dependencies (uses uv)
+uv sync
+
+# Install with dev dependencies (for testing)
+uv sync --all-extras
+
+# Run the MCP server locally
+uv run avanza-mcp
+
+# Run all tests
+uv run pytest tests/
+
+# Run unit tests only (fast, mocked)
+uv run pytest tests/unit -v
+
+# Run integration tests (hits real API)
+uv run pytest tests/integration -v
+```
+
+## Installation for MCP Clients
+
+For Claude Desktop or other MCP clients, add to your MCP config:
+
+```json
+{
+  "mcpServers": {
+    "avanza": {
+      "command": "uvx",
+      "args": ["avanza-mcp"]
+    }
+  }
+}
+```
+
+## Architecture
+
+```
+src/avanza_mcp/
+├── __init__.py              # FastMCP server instance, entry point
+├── client/
+│   ├── base.py              # Async httpx client with retry logic & connection pooling
+│   ├── endpoints.py         # API endpoint URL definitions
+│   └── exceptions.py        # Custom exceptions (AvanzaAPIError, etc.)
+├── services/
+│   ├── market_data_service.py  # Stock & fund data operations
+│   └── search_service.py       # Search operations
+├── tools/
+│   ├── market_data.py       # Stock tools (get_stock_info, get_dividends, etc.)
+│   ├── funds.py             # Fund tools (get_fund_info, get_fund_holdings, etc.)
+│   └── search.py            # Search tools
+├── models/
+│   ├── stock.py             # Stock Pydantic models (Quote, StockInfo, etc.)
+│   ├── fund.py              # Fund Pydantic models (FundInfo, FundSustainability, etc.)
+│   ├── search.py            # Search response models
+│   └── common.py            # Shared enums (InstrumentType, TimePeriod)
+├── resources/               # MCP resources
+└── prompts/                 # MCP prompts
+```
+
+## Key Design Patterns
+
+### HTTP Client with Retry
+The client uses tenacity for automatic retries on transient failures:
+- Retries on: timeouts, network errors, 5xx server errors
+- Does NOT retry on: 4xx client errors (400, 404, etc.)
+- Exponential backoff: 2-10 seconds between retries, max 3 attempts
+
+### Pydantic Models
+All models use consistent ConfigDict:
+```python
+MODEL_CONFIG = ConfigDict(
+    populate_by_name=True,      # Support both camelCase and snake_case
+    str_strip_whitespace=True,  # Clean string inputs
+    validate_assignment=True,   # Validate on assignment
+    extra="allow",              # Don't fail on unknown API fields
+)
+```
+
+### Tool Pattern
+Tools follow this pattern:
+```python
+@mcp.tool()
+async def get_something(ctx: Context, instrument_id: str) -> dict:
+    ctx.info(f"Fetching data for ID: {instrument_id}")
+    async with AvanzaClient() as client:
+        service = MarketDataService(client)
+        result = await service.get_something(instrument_id)
+    return result.model_dump(by_alias=True, exclude_none=True)
+```
+
+## Available Tools
+
+**Search:** search_instruments, get_instrument_by_order_book_id
+
+**Stocks:** get_stock_info, get_stock_quote, get_stock_analysis, get_stock_chart, get_orderbook, get_marketplace_info, get_recent_trades, get_broker_trade_summary, get_dividends, get_company_financials
+
+**Funds:** get_fund_info, get_fund_sustainability, get_fund_chart, get_fund_chart_periods, get_fund_description, get_fund_holdings

avanza_mcp-1.0.0/DEVELOPMENT.md

@@ -0,0 +1,125 @@
+# Development Guide - Avanza MCP Server
+
+This guide explains how to develop and test the Avanza MCP server locally, including integration with Claude Desktop.
+
+## 🚀 Quick Start
+
+### Prerequisites
+
+- Python 3.12 or higher
+- [uv](https://github.com/astral-sh/uv) package manager
+- [Claude Desktop](https://claude.ai/download) (optional, for MCP testing)
+
+### Initial Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/yourusername/avanza-mcp.git
+cd avanza-mcp
+
+# Install dependencies
+uv sync
+
+# Verify installation
+uv run python -c "from avanza_mcp import mcp; print('✓ Import successful')"
+```
+
+### Test with Claude Desktop
+
+This is the **recommended way** to test the full MCP integration.
+
+#### Step 1: Configure Claude Desktop for Local Development
+
+Edit your Claude Desktop configuration file:
+
+**Linux:** `~/.claude.json`
+
+Add the local development configuration:
+
+```json
+{
+  "mcpServers": {
+    "avanza-dev": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "/absolute/path/to/avanza-mcp",
+        "run",
+        "avanza-mcp"
+      ]
+    }
+  }
+}
+```
+
+**Replace `/absolute/path/to/avanza-mcp`** with your actual project path:
+
+```bash
+# Get the absolute path
+pwd
+# Example: /Users/username/projects/avanza-mcp
+```
+
+#### Step 2: Restart Claude Desktop
+
+1. Quit Claude Desktop completely
+2. Start Claude Desktop again
+3. The MCP server will be loaded automatically
+
+#### Step 3: Verify Connection
+
+In Claude Desktop, ask:
+
+```
+Can you list the available MCP tools?
+```
+
+You should see all Avanza tools listed.
+
+#### Step 4: Test Tools
+
+Try these queries in Claude Desktop:
+
+```
+# Search for stocks
+Search for Volvo stock on Avanza
+
+# Get stock quote
+Get the current stock quote for Volvo B (ID: 5269)
+
+# Get historical chart
+Show me a 3-month price chart for Ericsson (ID: 5286)
+
+# Get fund sustainability
+What's the ESG score for Avanza Zero fund (ID: 41567)?
+
+# Get order book
+Show me the order book depth for H&M (ID: 5364)
+
+# Get dividends (new)
+What dividends has SEB paid over the years?
+
+# Get fund holdings (new)
+Show me the portfolio allocation for Avanza Global fund
+```
+
+## 🧪 Running Tests
+
+```bash
+# Install dev dependencies
+uv sync --all-extras
+
+# Run all tests
+uv run pytest tests/
+
+# Run unit tests only (fast, no API calls)
+uv run pytest tests/unit -v
+
+# Run integration tests (hits real API, use sparingly)
+uv run pytest tests/integration -v --tb=short
+```
+
+### Test Coverage
+
+- **Unit tests** (`tests/unit/`): Test client, models, and error handling with mocked responses
+- **Integration tests** (`tests/integration/`): Test all 18 tools against the real Avanza API

avanza_mcp-1.0.0/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ante Wall
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

avanza_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: avanza-mcp
+Version: 1.0.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.0.0b1
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+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
+
+A Model Context Protocol (MCP) server providing access to Avanza's public API. Get real-time Swedish stock quotes, fund information, charts, and comprehensive market data.
+
+## ⚠️ 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.
+
+## 🛠️ MCP Tools
+
+### Search & Discovery
+| Tool | Description |
+|------|-------------|
+| `search_instruments` | Find stocks, funds, ETFs by name or symbol |
+| `get_instrument_by_order_book_id` | Look up instruments by order book ID |
+
+### Stock Analysis
+| Tool | Description |
+|------|-------------|
+| `get_stock_info` | Complete stock information with fundamentals |
+| `get_stock_quote` | Real-time price and volume data |
+| `get_stock_analysis` | Financial ratios by year and quarter |
+| `get_stock_chart` | Historical OHLC price data |
+| `get_orderbook` | Order book depth with bid/ask levels |
+| `get_marketplace_info` | Trading hours and market status |
+| `get_recent_trades` | Latest executed trades |
+| `get_broker_trade_summary` | Broker buy/sell activity |
+| `get_dividends` | Historical dividend data |
+| `get_company_financials` | Annual and quarterly financial statements |
+
+### Fund Analysis
+| Tool | Description |
+|------|-------------|
+| `get_fund_info` | Complete fund information with performance |
+| `get_fund_sustainability` | ESG scores and sustainability metrics |
+| `get_fund_chart` | Historical performance charts |
+| `get_fund_chart_periods` | Performance across all time periods |
+| `get_fund_description` | Detailed fund description |
+| `get_fund_holdings` | Portfolio allocation (country, sector, top holdings) |
+
+## 💡 MCP Prompts
+
+- `analyze_stock` - Comprehensive stock analysis workflow
+- `compare_funds` - Multi-fund comparison template
+- `screen_dividend_stocks` - Dividend stock screening
+
+
+### Configuration for MCP Clients
+
+For Claude Desktop or other MCP clients, add to your configuration:
+
+```json
+{
+  "mcpServers": {
+    "avanza": {
+      "command": "uvx",
+      "args": ["avanza-mcp"]
+    }
+  }
+}
+```
+
+### Usage in Claude Desktop
+
+Once configured, you can ask Claude:
+
+- "Search for Volvo stock on Avanza"
+- "Get the latest stock quote for Ericsson"
+- "Show me sustainable Swedish funds"
+- "What's in the order book for H&M?"
+- "Compare the performance of these three funds"
+- "What dividends has SEB paid over the years?"
+- "Show me the portfolio holdings for Avanza Global fund"
+
+## 📄 License
+
+MIT License - See [LICENSE.md](LICENSE.md) for details.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

avanza_mcp-1.0.0/README.md

@@ -0,0 +1,83 @@
+# Avanza MCP Server
+
+A Model Context Protocol (MCP) server providing access to Avanza's public API. Get real-time Swedish stock quotes, fund information, charts, and comprehensive market data.
+
+## ⚠️ 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.
+
+## 🛠️ MCP Tools
+
+### Search & Discovery
+| Tool | Description |
+|------|-------------|
+| `search_instruments` | Find stocks, funds, ETFs by name or symbol |
+| `get_instrument_by_order_book_id` | Look up instruments by order book ID |
+
+### Stock Analysis
+| Tool | Description |
+|------|-------------|
+| `get_stock_info` | Complete stock information with fundamentals |
+| `get_stock_quote` | Real-time price and volume data |
+| `get_stock_analysis` | Financial ratios by year and quarter |
+| `get_stock_chart` | Historical OHLC price data |
+| `get_orderbook` | Order book depth with bid/ask levels |
+| `get_marketplace_info` | Trading hours and market status |
+| `get_recent_trades` | Latest executed trades |
+| `get_broker_trade_summary` | Broker buy/sell activity |
+| `get_dividends` | Historical dividend data |
+| `get_company_financials` | Annual and quarterly financial statements |
+
+### Fund Analysis
+| Tool | Description |
+|------|-------------|
+| `get_fund_info` | Complete fund information with performance |
+| `get_fund_sustainability` | ESG scores and sustainability metrics |
+| `get_fund_chart` | Historical performance charts |
+| `get_fund_chart_periods` | Performance across all time periods |
+| `get_fund_description` | Detailed fund description |
+| `get_fund_holdings` | Portfolio allocation (country, sector, top holdings) |
+
+## 💡 MCP Prompts
+
+- `analyze_stock` - Comprehensive stock analysis workflow
+- `compare_funds` - Multi-fund comparison template
+- `screen_dividend_stocks` - Dividend stock screening
+
+
+### Configuration for MCP Clients
+
+For Claude Desktop or other MCP clients, add to your configuration:
+
+```json
+{
+  "mcpServers": {
+    "avanza": {
+      "command": "uvx",
+      "args": ["avanza-mcp"]
+    }
+  }
+}
+```
+
+### Usage in Claude Desktop
+
+Once configured, you can ask Claude:
+
+- "Search for Volvo stock on Avanza"
+- "Get the latest stock quote for Ericsson"
+- "Show me sustainable Swedish funds"
+- "What's in the order book for H&M?"
+- "Compare the performance of these three funds"
+- "What dividends has SEB paid over the years?"
+- "Show me the portfolio holdings for Avanza Global fund"
+
+## 📄 License
+
+MIT License - See [LICENSE.md](LICENSE.md) for details.
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.

avanza_mcp-1.0.0/justfile

@@ -0,0 +1,81 @@
+# Avanza MCP Server
+
+# Show all commands
+default:
+    @just --list
+
+# Install dependencies
+install:
+    uv sync
+
+# Run the MCP server
+run:
+    uv run avanza-mcp
+
+# Build the package
+build:
+    uv build
+
+# Clean build artifacts
+clean:
+    rm -rf dist/ build/ *.egg-info
+    find . -type d -name __pycache__ -exec rm -rf {} +
+
+# Get current version
+version:
+    @grep '^__version__ = ' src/avanza_mcp/__init__.py | cut -d'"' -f2
+
+# Bump version and trigger CI publish
+release version_part="patch":
+    #!/usr/bin/env bash
+    set -euo pipefail
+
+    # Check for uncommitted changes
+    if [[ -n $(git status -s) ]]; then
+        echo "Error: Uncommitted changes detected"
+        git status -s
+        exit 1
+    fi
+
+    # Get current version
+    current=$(grep '^__version__ = ' src/avanza_mcp/__init__.py | cut -d'"' -f2)
+    echo "Current: $current"
+
+    # Bump version
+    IFS='.' read -r major minor patch <<< "$current"
+    case "{{version_part}}" in
+        major) major=$((major + 1)); minor=0; patch=0 ;;
+        minor) minor=$((minor + 1)); patch=0 ;;
+        patch) patch=$((patch + 1)) ;;
+        *) echo "Error: Use major, minor, or patch"; exit 1 ;;
+    esac
+
+    new_version="$major.$minor.$patch"
+    echo "New: $new_version"
+
+    # Update version in __init__.py
+    sed -i "s/^__version__ = \".*\"/__version__ = \"$new_version\"/" src/avanza_mcp/__init__.py
+
+    # Show diff
+    git diff src/avanza_mcp/__init__.py
+
+    # Commit and tag
+    git add src/avanza_mcp/__init__.py
+    git commit -m "Bump version to $new_version"
+    git tag "v$new_version"
+    git push origin master
+    git push origin "v$new_version"
+
+    echo ""
+    echo "✓ Released $new_version"
+    echo "✓ CI will build and publish to PyPI"
+    echo "✓ https://github.com/antewall/avanza-mcp/actions"
+
+# Release shortcuts
+release-patch: (release "patch")
+release-minor: (release "minor")
+release-major: (release "major")
+
+# Test imports
+test:
+    uv run python -c "from avanza_mcp import mcp, __version__; print(f'v{__version__}')"