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 .env:

   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:

docker pull ghcr.io/toomy1992/wealthfolio-mcp:latest
docker run -p 8000:8000 --env-file .env ghcr.io/toomy1992/wealthfolio-mcp:latest

Usage

Starting the Server

uvicorn src.mcp_server:app --reload

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

API Endpoints

• GET /portfolio - Get comprehensive portfolio data including accounts, valuations, assets, and historical performance
• POST /sync - Trigger portfolio synchronization (placeholder for future implementation)

Testing the API

Visit http://127.0.0.1:8000/docs for interactive API documentation.

Or test with curl:

curl -X GET "http://127.0.0.1:8000/portfolio" -H "accept: application/json"

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

Schedule Trigger → HTTP Request (Portfolio) → Data Transform → Email Notification

Configuration

Environment Variables

Variable	Description	Default
API_KEY	Your Wealthfolio API key	Required
API_BASE_URL	Wealthfolio API base URL	https://wealthfolio.labruntipi.io/api/v1
asset_filters	Asset types to filter	["stocks", "crypto"]

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:

ghcr.io/toomy1992/wealthfolio-mcp:latest

Development

Project Structure

wealthfolio-mcp/
├── src/
│   ├── mcp_server.py      # FastAPI MCP server
│   └── api_client.py       # Wealthfolio API client
├── config/
│   └── settings.py         # Configuration management
├── tests/                  # Unit and integration tests
├── .github/
│   └── workflows/          # GitHub Actions
├── Dockerfile              # Docker build configuration
├── docker-compose.yml      # Local development setup
├── requirements.txt        # Python dependencies
├── .env.example           # Environment template
└── README.md              # This file

Running Tests

# Run all tests
pytest tests/

# Or use the Makefile
make test

Development Commands

Use the provided Makefile for common development tasks:

make install      # Install dependencies
make dev          # Run development server
make test         # Run tests
make lint         # Run linting
make format       # Format code
make docker-build # Build Docker image
make docker-run   # Run Docker container

Docker Development

# Build locally
docker build -t wealthfolio-mcp .

# Run with hot reload for development
docker run -p 8000:8000 -v $(pwd):/app --env-file .env wealthfolio-mcp

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:

uvicorn src.mcp_server:app --reload --log-level debug

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