The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Ghostfolio MCP listing page.
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.
The easiest way to get started is to install from PyPI:
Remember to configure the environment variables for your Ghostfolio instance before running the server:
For more details, visit: https://pypi.org/project/ghostfolio-mcp/
For development with additional tools:
The server optionally supports Sentry for error tracking, performance monitoring, and debugging. Sentry integration is completely optional and only initialized if configured.
To enable Sentry monitoring, install the optional dependency:
Enable Sentry by setting the SENTRY_DSN environment variable in your .env file:
When enabled, Sentry automatically captures:
.env fileSentry 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.
get_accounts: Get all accounts in your portfolio including account types and balancesget_account_balances: Get account balances for a specific accountcreate_account: Create a new account in your portfoliodelete_account: Delete an existing account from your portfolio (destructive operation)get_account_details: Get details for a specific accountupdate_account: Update settings or details of an existing accounttransfer_account_balance: Transfer cash balances between two accountscreate_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 historyget_portfolio_performance: Get portfolio performance data including returns, benchmarks, and performance metricsget_portfolio_holdings: Get portfolio holdings and positions including allocations and asset breakdownsget_portfolio_details: Get comprehensive portfolio details including accounts, positions, and summaryget_position: Get position details for a specific symbol from a data sourceget_investments: Get investment data grouped by time period showing cash flows and contributionsget_dividends: Get dividend data grouped by time period showing dividend payments and yieldget_orders: Get all activities/orders from your portfolio, optionally filtered by accountcreate_activity: Create a single new transaction/activity in your portfolio (BUY, SELL, DIVIDEND, INTEREST, FEE, etc.)delete_activity: Delete a single activity/transaction by its ID (destructive operation)get_benchmarks: Get all configured benchmarksget_benchmark_performance: Compare portfolio performance against a benchmark symbol starting from a specific dateget_watchlist: Get all items in the user's watchlistadd_to_watchlist: Add a symbol to the user's watchlistremove_from_watchlist: Remove a symbol from the user's watchlistget_exchange_rate: Get the exchange rate for a given currency symbol on a specific dateexport_portfolio: Export portfolio activities/transactions data as JSONget_market_data_for_asset: Get market data for a specific assetadd_market_data_points: Add one or more market data points for an asset (typically a MANUAL data source — Ghostfolio rejects writes for auto-fetched sources)get_symbol_data: Get symbol data for a specific asset from a data sourceget_historical_data: Get historical data for a specific symbol on a specific datelookup_symbols: Search for symbols using a query stringget_asset_profile: Get asset profile information for a specific symbolupsert_asset_profile: Create-or-update an asset profile (idempotent; tolerates Ghostfolio's HTTP 500 on the create step and relies on the subsequent PATCH as the source of truth)delete_asset_profile: Delete an asset profile (destructive operation; may delete associated activities and market data depending on backend rules)import_transactions: Import transactions into your portfolio (bulk import operation)get_dividends_for_import: Fetch historical dividend data formatted for import for a specific symbolget_health: Get system health status of the Ghostfolio backend serviceget_platforms: Get list of available platforms (brokers, exchanges, etc.) for account trackingget_user_info: Get user information and settingsThe server supports a read-only mode that disables all write operations for safe monitoring:
When enabled, this mode prevents any modifications to your portfolio data while still allowing full read access to all information.
You can disable specific categories of tools by setting disabled tags:
Available tags include:
account - Account management tools (create, delete, update, get accounts)portfolio - Portfolio analysis and performance toolssymbol - Symbol lookup and data toolsimport - Data import toolsasset - Asset profile toolsuser - User information toolssystem - System health and platform information toolsactivities - Activity/transaction management tools (create, delete activities)watchlist - Watchlist management toolsexchange-rate - Currency exchange rate toolsexport - Data export toolsbenchmark - Benchmark toolsThe server supports rate limiting to control API usage and prevent abuse. If enabled, requests are limited per client using a sliding window algorithm.
Enable rate limiting by setting the following environment variables in your .env file:
If RATE_LIMIT_ENABLED is set to true, the server will apply rate limiting middleware. Adjust RATE_LIMIT_MAX_REQUESTS and RATE_LIMIT_WINDOW_MINUTES as needed for your environment.
FastMCP tool search can reduce prompt size for servers with many tools.
When enabled, list_tools returns two synthetic tools:
search_tools: Finds matching tools and returns their full schemascall_tool: Executes any discovered tool by nameEnable it with:
bm25 supports natural language queries, while regex uses a regex
pattern input for deterministic matching.
Tool search respects existing visibility controls (read-only mode and disabled tags).
The server supports SSL certificate verification and custom timeout settings:
The server supports multiple transport protocols for different deployment scenarios:
The default transport uses standard input/output for communication. This is ideal for local usage and integration with tools that communicate via stdin/stdout:
For network-based deployments, you can use HTTP with Server-Sent Events. This allows the MCP server to be accessed over HTTP with real-time streaming:
When using SSE transport with a bearer token, clients must include the token in their requests:
The HTTP Streamable transport provides HTTP-based communication with request/response streaming. This is ideal for web integrations and tools that need HTTP endpoints:
When using streamable transport with a bearer token:
Note: The HTTP transport requires proper JSON-RPC formatting with jsonrpc and id fields. The server may also require session initialization for some operations.
A static bearer token is enough for machine-to-machine clients, but many MCP clients can only authenticate over OAuth with Dynamic Client Registration. For those, the server can act as an OAuth interface in front of an existing OIDC identity provider (Authentik, Keycloak, PocketID, Auth0, Entra ID, ...) using FastMCP's OIDCProxy. Clients register and authenticate against this server; the server brokers the flow upstream. No Ghostfolio credential ever reaches the client.
This applies to the sse and http transports only.
Create a confidential client (client ID + secret) on your identity provider with the redirect URI set to OIDC_BASE_URL + OIDC_REDIRECT_PATH, for example https://ghostfolio-mcp.example.com/auth/callback.
OIDC is entirely optional. Leaving these unset keeps the existing behaviour, and a partially configured setup is ignored with a warning rather than half-enabled. When OIDC is configured it takes precedence over MCP_HTTP_BEARER_TOKEN.
Optional settings:
OIDC_ALLOWED_REDIRECT_URIS restricts which clients may complete the flow. Leaving it unset accepts any redirect URI a client registers, so set it to the hosts you expect, for example https://example.com/*.
Set OIDC_VERIFY_ID_TOKEN=true if your identity provider issues opaque (non-JWT) access tokens; the id_token is then verified instead.
OIDC_FORWARD_RESOURCE is off by default because identity providers that do not implement RFC 8707 resource indicators reject the authorization request with invalid_request, which breaks login immediately after consent. Turn it on only if your provider supports resource indicators. Token audience binding is unaffected either way.
Client registrations and encrypted tokens are stored on disk, under FastMCP's data directory. If that directory is not persistent, every restart forces all clients to register and authenticate again. The Docker image sets FASTMCP_HOME=/data, so mount a volume there:
OIDC_BASE_URL must be the externally reachable HTTPS URL, and the proxy must forward the Host header unchanged, otherwise the OAuth metadata this server advertises will point at the wrong host.
Ghostfolio supports multiple data sources for market data and symbols:
When using tools that require a data source parameter, specify the appropriate source for your asset type.
A Docker images are available on GitHub Packages for easy deployment.
When OIDC authentication is enabled, mount a volume on /data so OAuth client registrations survive container recreation.
git checkout -b feature/amazing-feature)uv run pytest && uv run ruff check .)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)GNU Affero General Public License - see LICENSE file for details.