Wealthfolio MCP Server

A Model Context Protocol (MCP) server that integrates with Wealthfolio to provide portfolio data, valuations, and analytics to OpenWebUI and other MCP-compatible applications.

Features

• Real-time Portfolio Data: Fetch current portfolio valuations, holdings, and performance metrics

• Account Management: Access all your Wealthfolio accounts and their details

• Asset Information: Get comprehensive asset profiles and market data

• Historical Valuations: Retrieve portfolio performance history over time

• OpenWebUI Integration: Seamlessly integrate with OpenWebUI for enhanced AI interactions

• n8n Workflow Support: Ready for automation workflows with n8n

Prerequisites

• Python 3.10+

• Wealthfolio API access

• OpenWebUI (for UI integration)

• n8n (optional, for workflow automation)

Installation

Option 1: Local Development

1. Clone the repository:

   git clone https://github.com/toomy1992/Wealthfolio-MCP.git cd Wealthfolio-MCP

2. Install dependencies:

   pip install -r requirements.txt

3. Configure environment:

   cp .env.example .env # Edit .env with your Wealthfolio API key

4. Update your API key in

   API_KEY=your_wealthfolio_api_key_here API_BASE_URL=https://wealthfolio.labruntipi.io/api/v1

Option 2: Docker (Recommended)

1. Clone the repository:

   git clone https://github.com/toomy1992/Wealthfolio-MCP.git cd Wealthfolio-MCP

2. Configure environment:

   cp .env.example .env # Edit .env with your Wealthfolio API key

3. Run with Docker Compose:

   docker-compose up -d

4. Or build and run manually:

   docker build -t wealthfolio-mcp . docker run -p 8000:8000 --env-file .env wealthfolio-mcp

Option 3: Pre-built Docker Image

Pull the latest release from GitHub Container Registry:

Usage

Starting the Server

The server will start on http://127.0.0.1:8000

API Endpoints

Portfolio Data Endpoints

• GET /portfolio - Get comprehensive portfolio data including accounts, valuations, assets, and historical performance

  • Uses: get_accounts(), get_latest_valuations(), get_assets(), get_valuation_history(), fetch_portfolio_data()

• GET /accounts - Get all accounts

  • Uses: get_accounts()

• GET /valuations/latest - Get latest valuations for specified accounts

  • Query params: account_ids (list of account IDs)

  • Uses: get_latest_valuations()

• GET /assets - Get all available assets

  • Uses: get_assets()

• GET /valuations/history - Get historical valuations for a specified account and time period

  • Query params: account_id (default: "TOTAL"), days (default: 30)

  • Uses: get_valuation_history()

• GET /holdings/item - Get a specific holding item for an account and asset

  • Query params: account_id, asset_id

  • Uses: get_holding_item()

System Endpoints

• POST /sync - Trigger portfolio synchronization (placeholder for future implementation)

Testing the API

Visit http://127.0.0.1:8000/docs for interactive OpenAPI/Swagger documentation with full schema definitions.

Or test with curl:

OpenAPI / Swagger Documentation

The server automatically generates comprehensive OpenAPI 3.0 documentation:

• Interactive Swagger UI: http://localhost:8000/docs

• OpenAPI JSON Schema: http://localhost:8000/openapi.json

All endpoints are documented with:

• Detailed descriptions of what data is fetched

• Information about which WealthfolioClient methods are used

• Parameter documentation and defaults

• Response schemas

MCP Integration with OpenAPI

This server is designed to work as a universal MCP (Model Context Protocol) server with OpenAPI support:

Using mcpo Proxy (Recommended)

To expose this MCP server through standard REST/OpenAPI endpoints with the mcpo proxy:

This will:

• Convert MCP tools to REST endpoints

• Auto-generate interactive OpenAPI documentation

• Make the server accessible via standard HTTP

• Enable integration with OpenWebUI and other platforms

Docker with mcpo

OpenWebUI Integration

1. Install the MCP plugin in OpenWebUI

2. Configure the MCP server URL: http://127.0.0.1:8000

3. Add tools for portfolio queries:

   • Portfolio summary

   • Account valuations

   • Asset performance

   • Historical charts

Example OpenWebUI Queries

• "What's my current portfolio value?"

• "Show me my account performance over the last month"

• "Which assets have the highest gains?"

• "Display my portfolio allocation by asset type"

n8n Integration

Create automated workflows in n8n:

1. HTTP Request Node: Connect to http://127.0.0.1:8000/portfolio

2. Schedule Trigger: Set up daily/weekly portfolio reports

3. Data Processing: Transform portfolio data for notifications

4. Email/Discord Integration: Send automated portfolio updates

Sample n8n Workflow

Configuration

Environment Variables

API Endpoints Used

The server integrates with these Wealthfolio API endpoints:

• /api/v1/accounts - Account information

• /api/v1/valuations/latest - Current portfolio valuations

• /api/v1/assets - Asset profiles and data

• /api/v1/valuations/history - Historical performance data

• /api/v1/holdings/item - Individual holding details

CI/CD and Releases

This project uses GitHub Actions for automated building, testing, and releasing.

Automated Versioning

• Versions start from 0.1.0

• Patch versions are automatically incremented on each push to main

• Releases are created automatically with Docker images

GitHub Actions Workflow

The CI/CD pipeline includes:

• Testing: Runs pytest and linting on all pushes

• Docker Build: Builds and pushes Docker images to GitHub Container Registry

• Automated Releases: Creates GitHub releases with version tags

Docker Images

Pre-built images are available at:

Development

Project Structure

Running Tests

Development Commands

Use the provided Makefile for common development tasks:

Docker Development

Adding New Features

1. Extend the WealthfolioClient class in api_client.py

2. Add new endpoints in mcp_server.py

3. Update the README with new functionality

4. Add tests for new features

5. Update the Dockerfile if new dependencies are added

Troubleshooting

Common Issues

1. API Key Invalid: Verify your API key in .env

2. Connection Errors: Check internet connectivity and API URL

3. Empty Responses: Ensure your Wealthfolio instance has data

4. CORS Issues: Configure OpenWebUI CORS settings for the MCP server

Debug Mode

Run with debug logging:

Contributing

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests

5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

• Issues: GitHub Issues

• Discussions: GitHub Discussions

• Wealthfolio Community: Discord

Releases and Versioning

This project uses automated semantic versioning starting from 0.1.0. Each push to the main branch automatically:

1. Increments the patch version (e.g., 0.1.0 → 0.1.1)

2. Creates a new GitHub release

3. Builds and pushes Docker images to GitHub Container Registry

Latest Release

Changelog

v0.1.0

• Initial release

• Wealthfolio API integration with real endpoints

• FastAPI MCP server implementation

• Docker containerization

• OpenWebUI compatibility

• n8n workflow support

• Automated CI/CD with GitHub Actions

• Comprehensive test suite

Build with Grok