Ghostfolio MCP

Ghostfolio MCP Server

Let AI agents analyze and manage your Ghostfolio investment portfolio

Installation · Tools · Configuration · Security

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
• Create, delete, and manage individual transactions and activities
• 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
• Monitor system health and platform availability

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
• Bearer token or OIDC/OAuth authentication for HTTP transports

🚀 Installation

Prerequisites

• Python 3.11 to 3.15
• 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

1. Clone the repository:

git clone https://github.com/mhajder/ghostfolio-mcp.git

cd ghostfolio-mcp

1. Install dependencies:

# Using UV (recommended)

uv sync

Or using pip

pip install -e .

1. Configure environment variables:

cp .env.example .env

Edit .env with your Ghostfolio URL and token

1. Run the server:

# Using UV (recommended)

uv run ghostfolio-mcp

Or using the installed command directly

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 .

Run type checking

uv run ty check .

Setup prek hooks

uv run prek install

🔧 Configuration

Environment Variables

A blank or whitespace-only value counts as unset and uses the default. Boolean settings accept true/false, 1/0, yes/no and on/off (any case). Any other value stops the server at startup, so a typo cannot silently turn read-only mode or TLS verification off.

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

RATE_LIMIT_ENABLED=false RATE_LIMIT_MAX_REQUESTS=60 RATE_LIMIT_WINDOW_MINUTES=1

Tool Search Transform (Optional)

Set TOOL_SEARCH_ENABLED true to replace full tool listings with search_tools + call_tool

TOOL_SEARCH_ENABLED=false

Search strategy: bm25 (natural language) or regex (pattern match)

TOOL_SEARCH_STRATEGY=bm25

Maximum number of tools returned by search_tools

TOOL_SEARCH_MAX_RESULTS=5

Sentry Error Tracking (Optional)

Set SENTRY_DSN to enable error tracking and performance monitoring

SENTRY_DSN=https://your-key@o12345.ingest.us.sentry.io/6789

Optional Sentry configuration

SENTRY_TRACES_SAMPLE_RATE=1.0

SENTRY_SEND_DEFAULT_PII=false

SENTRY_ENVIRONMENT=production

SENTRY_RELEASE=1.2.3

SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0

SENTRY_PROFILE_LIFECYCLE=trace

SENTRY_ENABLE_LOGS=true

MCP Transport Configuration

Transport type: 'stdio' (default), 'sse' (Server-Sent Events), or 'http' (HTTP Streamable)

'streamable-http' is accepted as an alias for 'http'. Any other value stops

the server at startup.

MCP_TRANSPORT=stdio

HTTP Transport Settings (used when MCP_TRANSPORT=sse or MCP_TRANSPORT=http)

Host to bind the HTTP server (default: 127.0.0.1)

MCP_HTTP_HOST=127.0.0.1

Port to bind the HTTP server (default: 8000)

MCP_HTTP_PORT=8000

Optional bearer token for authentication (leave empty for no auth)

MCP_HTTP_BEARER_TOKEN=

OIDC / OAuth Authentication (optional, for remote hosting)

Set all four to enable; takes precedence over MCP_HTTP_BEARER_TOKEN

OIDC_CONFIG_URL=https://id.example.com/.well-known/openid-configuration

OIDC_CLIENT_ID=

OIDC_CLIENT_SECRET=

OIDC_BASE_URL=https://ghostfolio-mcp.example.com

Optional OIDC settings

OIDC_REDIRECT_PATH=/auth/callback

OIDC_REQUIRED_SCOPES=

OIDC_ALLOWED_REDIRECT_URIS=

OIDC_VERIFY_ID_TOKEN=false

OIDC_FORWARD_RESOURCE=false

Sentry Error Tracking & Monitoring (Optional)

The server optionally supports Sentry for error tracking, performance monitoring, and debugging. Sentry integration is completely optional and only initialized if configured.

Installation

To enable Sentry monitoring, install the optional dependency:

# Using UV (recommended)

uv sync --extra sentry

Configuration

Enable Sentry by setting the SENTRY_DSN environment variable in your .env file:

# Required: Sentry DSN for your project

SENTRY_DSN=https://your-key@o12345.ingest.us.sentry.io/6789

Optional: Performance monitoring sample rate (0.0-1.0, default: 1.0)

SENTRY_TRACES_SAMPLE_RATE=1.0

Optional: Include personally identifiable information (default: false).

When true, tool inputs and outputs (portfolio data) are sent to Sentry.

SENTRY_SEND_DEFAULT_PII=false

Optional: Environment name (e.g., "production", "staging")

SENTRY_ENVIRONMENT=production

Optional: Release version (auto-detected from package if not set)

SENTRY_RELEASE=1.2.2

Optional: Profiling - continuous profiling sample rate (0.0-1.0, default: 1.0)

SENTRY_PROFILE_SESSION_SAMPLE_RATE=1.0

Optional: Profiling - lifecycle mode for profiling (default: "trace")

Options: "all", "continuation", "trace"

SENTRY_PROFILE_LIFECYCLE=trace

Optional: Enable log capture as breadcrumbs and events (default: true)

SENTRY_ENABLE_LOGS=true

Features

When enabled, Sentry automatically captures:

• Exceptions & Errors: All unhandled exceptions with full context
• Performance Metrics: Request/response times and traces
• MCP Integration: Detailed MCP server activity and interactions
• Logs & Breadcrumbs: Application logs and event trails for debugging
• Context Data: Environment, client info, and request parameters

Getting a Sentry DSN

1. Create a free account at sentry.io
2. Create a new Python project
3. Copy your DSN from the project settings
4. Set it in your .env file

Disabling Sentry

Sentry is completely optional. If you don't set SENTRY_DSN, the server will run normally without any Sentry integration, and no monitoring data will be collected.

🧰 Available Tools

Account Management Tools

• get_accounts: Get all accounts in your portfolio including account types and balances
• get_account_balances: Get account balances for a specific account
• create_account: Create a new account in your portfolio
• delete_account: Delete an existing account from your portfolio (destructive operation)
• get_account_details: Get details for a specific account
• update_account: Update settings or details of an existing account
• transfer_account_balance: Transfer cash balances between two accounts
• create_account_balance: Set an account's balance for a specific date in its balance history (defaults to today)
• delete_account_balance: Delete a single entry from an account's balance history

Portfolio & Transaction Management Tools

• get_portfolio_performance: Get portfolio performance data including returns, benchmarks, and performance metrics
• get_portfolio_holdings: Get portfolio holdings and positions including allocations and asset breakdowns
• get_portfolio_details: Get comprehensive portfolio details including accounts, positions, and summary
• get_position: Get position details for a specific symbol from a data source
• get_investments: Get investment data grouped by time period showing cash flows and contributions
• get_dividends: Get dividend data grouped by time period showing dividend payments and yield
• get_orders: Get all activities/orders from your portfolio, optionally filtered by account
• create_activity: Create a single new transaction/activity in your portfolio (BUY, SELL, DIVIDEND, INTEREST, FEE, etc.), optionally with tags
• update_activity: Update an existing activity/transaction, including its tags; fields you don't pass keep their current values
• delete_activity: Delete a single activity/transaction by its ID (destructive operation)

Benchmark Tools

• get_benchmarks: Get all configured benchmarks
• `get_