Ghostfolio MCP Server
Ghostfolio MCP Server is a Python-based Model Context Protocol (MCP) server designed to provide advanced, programmable access to Ghostfolio portfolio management and financial data. It exposes a modern API for querying, analyzing, and managing your investment portfolio through Ghostfolio's comprehensive features. The server supports both read and write operations, robust security features, and is suitable for integration with automation tools, financial dashboards, and custom portfolio management applications.
Features
Core Features
- Query portfolio performance, holdings, and positions with flexible time ranges
- Retrieve comprehensive investment data including dividends, returns, and allocations
- Access detailed market data, asset profiles, and historical price information
- Monitor portfolio metrics, benchmarks, and performance comparisons
- Track orders, transactions, and account balances across multiple accounts
- Search and lookup financial symbols, stocks, ETFs, and other assets
- Get user information, settings, and account details
Management Operations
- Create and manage investment accounts with different currencies and platforms
- Import transactions and historical data from other platforms
- Configure read-only mode to restrict all write operations for safe monitoring
- Support for bulk transaction imports and portfolio data management
Advanced Capabilities
- Rate limiting and API security features
- Real-time portfolio monitoring and performance tracking
- Comprehensive logging and audit trails
- SSL/TLS support and configurable timeouts
- Extensible with custom middlewares and tag-based tool filtering
- Optional tool-search transform for large tool catalogs
Installation
Prerequisites
- Python 3.11 or higher
- Access to a Ghostfolio instance
- Valid Ghostfolio API token
Quick Install from PyPI
The easiest way to get started is to install from PyPI:
# Using UV (recommended)
uvx ghostfolio-mcp
# Or using pip
pip install ghostfolio-mcp
Remember to configure the environment variables for your Ghostfolio instance before running the server:
# Create environment configuration
export GHOSTFOLIO_URL=https://domain.tld:3333
export GHOSTFOLIO_TOKEN=your-ghostfolio-token
For more details, visit: https://pypi.org/project/ghostfolio-mcp/
Install from Source
- Clone the repository:
git clone https://github.com/mhajder/ghostfolio-mcp.git
cd ghostfolio-mcp
- Install dependencies:
# Using UV (recommended)
uv sync
# Or using pip
pip install -e .
- Configure environment variables:
cp .env.example .env
# Edit .env with your Ghostfolio URL and token
- Run the server:
# Using UV
uv run python run_server.py
# Or directly with Python
python run_server.py
# Or using the installed script
ghostfolio-mcp
Development Setup
For development with additional tools:
# Clone and install with development dependencies
git clone https://github.com/mhajder/ghostfolio-mcp.git
cd ghostfolio-mcp
uv sync --group dev
# Run tests
uv run pytest
# Run with coverage
uv run pytest --cov=src/
# Run linting and formatting
uv run ruff check .
uv run ruff format .
# Setup pre-commit hooks
uv run pre-commit install
Configuration
Environment Variables
# Ghostfolio Connection Details
GHOSTFOLIO_URL=https://domain.tld:3333
GHOSTFOLIO_TOKEN=your-ghostfolio-token
# SSL Configuration
GHOSTFOLIO_VERIFY_SSL=true
GHOSTFOLIO_TIMEOUT=30
# Read-Only Mode
# Set READ_ONLY_MODE true to disable all write operations (put, post, delete)
READ_ONLY_MODE=false
# Disabled Tags
# Comma-separated list of tags to disable tools for (empty by default)
# Example: GHOSTFOLIO_DISABLED_TAGS=portfolio,symbol
GHOSTFOLIO_DISABLED_TAGS=
# Logging Configuration
LOG_LEVEL=INFO
# Rate Limiting (requests per minute)
# Set RATE_LIMIT_ENABLED true to enable rate limitin
... [View full README on GitHub](https://github.com/mhajder/ghostfolio-mcp#readme)
