openwealth-mcp

OpenWealth MCP Server for Claude — enabling conversational AI agents to query Swiss wealth management data via OpenWealth APIs.

Status: Phase 3 - Publication Ready — V3 API complete, test PyPI validation in progress ✅

What Is This?

An open-source MCP (Model Context Protocol) server that enables AI agents to interact with Swiss wealth management systems through the OpenWealth API v3.2.0 standard (Custody Services API).

This server provides a standardized interface for AI assistants like Claude to:

• List customers in the portfolio (cursor-based pagination)
• Get positions for portfolio holdings and asset allocation
• Get transactions for trade history and cash movements

Phase 1 Scope: Read-only operations only (Custody Services API). Write operations excluded.

Built with Python 3.11+ and designed for Swiss financial institutions using the OpenWealth standard.

Installation

For End Users (Using the MCP Server)

Prerequisites:

• Python 3.11+ (check with python --version)
• Claude Desktop app (download here)
• OpenWealth sandbox credentials (contact OpenWealth Association for access)

Step 1: Install the package

pip install alpflo-openwealth-mcp

Step 2: Configure Claude Desktop

Add this to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "openwealth": {
      "command": "python",
      "args": ["-m", "openwealth_mcp"],
      "env": {
        "OPEN_WEALTH_USER": "your_username_here",
        "OPEN_WEALTH_PASSWORD": "your_password_here",
        "OPEN_WEALTH_BASE_URL": "https://api.openwealth.synpulse8.com/api/custody-services/v3"
      }
    }
  }
}

Step 3: Restart Claude Desktop

The OpenWealth tools will now be available in your Claude conversations:

• list_customers — Discover customers in your portfolio
• get_positions — View portfolio holdings and asset allocation
• get_transactions — Query transaction history

Example usage in Claude:

Show me all customers in my portfolio
What positions does customer C001 hold?
Get transactions for customer C001 in the last 30 days

Troubleshooting

"Server disconnected" error:

If Claude Desktop shows "Server disconnected", the package may not be installed globally:

# Install globally with pip
pip3 install alpflo-openwealth-mcp

# Or use the full path to your Python in the config
# macOS example:
{
  "mcpServers": {
    "openwealth": {
      "command": "/Library/Frameworks/Python.framework/Versions/3.13/bin/python3",
      "args": ["-m", "openwealth_mcp"],
      "env": { ... }
    }
  }
}

Check installation:

python3 -c "import openwealth_mcp; print(openwealth_mcp.__version__)"

Development Setup

For Contributors (developing the MCP server itself)

Prerequisites

• Python 3.11+
• uv package manager (install here)
• OpenWealth sandbox credentials

Quick Start

# Clone repository
git clone https://github.com/alpflo/openwealth-mcp.git
cd openwealth-mcp

# Install dependencies
uv sync

# Run tests
pytest tests/unit/ -v

# Type check
uv run pyright src/

See CLAUDE.md for complete development workflow and testing guidelines.

Current MCP Tools

Three Read-Only Tools (Specification Complete)

This project provides read-only access to portfolio and customer data via the OpenWealth Custody Services API v3.2.0.

Scope: Read-only Custody Services API operations only. Write operations and customer lifecycle management are excluded.

Full API specifications: See docs/API-REFERENCE.md

Architecture

Claude Desktop → MCP Server → OpenWealth Client → OpenWealth API (Sandbox)

Key principles: Type safety, stateless tools, structured logging, read-only operations.

See docs/ARCHITECTURE.md for complete design philosophy and technical patterns.

Documentation

Tech Stack

Python 3.11+ • Pydantic • MCP SDK • httpx • structlog

See docs/ARCHITECTURE.md for complete details.

Roadmap

• ✅ Phase 1: Foundation complete
• ✅ Phase 2: Implementation + testing complete (81.90% coverage)
• ✅ Phase 3: Published to PyPI v0.1.0

Current Status: Production release available on PyPI

Contributing

Contributions are welcome! Please:

1. Read CLAUDE.md for development setup and guidelines
2. Run tests locally: pytest tests/unit/ -v
3. Ensure type checking passes: uv run pyright src/
4. Follow Git workflow: feature branch → PR → review → merge

All contributions are licensed under Apache 2.0 (matching this repository).

See docs/ARCHITECTURE.md for design principles.

License

Apache License 2.0 — see LICENSE for full text.

Why Apache 2.0?

This project is licensed under Apache License 2.0 because:

1. Explicit Patent Grant — Protects users and contributors from patent litigation
2. Business-Friendly — Enables commercial use and proprietary extensions
3. Permissive — Allows free use, modification, and redistribution
4. Industry Standard — Widely adopted in AI tooling and wealth-tech ecosystems

Third-Party Notices

This project includes third-party libraries under Apache 2.0, MIT, and BSD licenses. See NOTICE for complete attribution and license information.

All dependencies are compatible with Apache 2.0. No GPL-licensed code is included.

Contributing

Contributions are welcome once the initial implementation is complete. All contributions are implicitly licensed under Apache 2.0 (matching the repository license). We will not require a separate Contributor License Agreement (CLA) but reserve the right to add one if governance needs evolve.

For now, see CLAUDE.md for development guidelines.

About

Organization: alpflo (GitHub: @alpflo)

Purpose: Enable AI agents to interact with Swiss wealth management systems through a standardized, type-safe interface.

Status: Production release v0.1.0 available on PyPI.

Resources

• OpenWealth Association: https://openwealth.swiss
• MCP Protocol: https://modelcontextprotocol.io
• Claude Desktop: https://claude.ai/download

Last updated: 2026-05-29
Status: Phase 3 - Publication Ready ✅