avanza-mcp: Instructions file for Claude Code

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

# 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:

{
  "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