使用说明内容（Markdown格式）

• 项目简介

  • 该仓库实现了一个基于 MCP 的后端服务器，核心功能是向 MCP 客户端暴露一组包装 Ghostfolio API 的工具（Tools），并通过中间件支持只读模式、标签过滤以及速率限制等安全特性。服务器通过 JSON-RPC 与客户端通信，支持多种传输方式（STDIO、SSE、HTTP）。同时提供对 Sentry 的可选集成，用于错误追踪与监控。

• 主要功能点

  • 提供一组与 Ghostfolio API 交互的工具，用于查询账户、投资组合、市场数据、交易等信息（只读模式下可控访问）。
  • 支持只读模式、禁用标签、以及对特定标签的工具/资源/提示进行过滤与隐藏。
  • 具备可选的速率限制中间件，防止滥用。
  • 支持多传输协议：STDIO、HTTP SSE、HTTP Streamable（需要在环境变量中配置 MCP_TRANSPORT、HOST、PORT、Bearer Token 等）。
  • 与 Ghostfolio 配置解耦，使用环境变量提供 Ghostfolio 连接信息、证书校验、超时等参数。
  • 若配置了 SENTRY_DSN，将启用 Sentry 集成进行错误与性能监控。

• 安装步骤

  • 确保环境中的 Python 版本为 3.11 及以上。
  • 通过 PyPI 安装（推荐）或从源码安装。
  • 安装后，设置 Ghostfolio 相关环境变量，包括 Ghostfolio 的 URL 与 Token，以及传输方式与安全设置。
  • 直接运行服务脚本（run_server.py）或通过安装脚本启动。

• 服务器配置（MCP 客户端用于连接该 MCP 服务器的配置信息） 重要说明：MCP 客户端需要的仅是连接该 MCP 服务器的参数，实际启动与连接参数以客户端实现为准。以下给出服务器启动时应配置的必要信息（以 JSON 形式呈现，客户端读取时不需要写代码）。

  { "server_name": "Ghostfolio MCP Server", "command": "ghostfolio-mcp", "args": [], "env": { "GHOSTFOLIO_URL": "<Ghostfolio 基础 URL，例如 https://domain.tld:3333>", "GHOSTFOLIO_TOKEN": "<Ghostfolio API 令牌>", "GHOSTFOLIO_VERIFY_SSL": "true", "GHOSTFOLIO_TIMEOUT": "30", "READ_ONLY_MODE": "false", "GHOSTFOLIO_DISABLED_TAGS": "", "RATE_LIMIT_ENABLED": "false", "RATE_LIMIT_MAX_REQUESTS": "60", "RATE_LIMIT_WINDOW_MINUTES": "1", "MCP_TRANSPORT": "stdio", "MCP_HTTP_HOST": "0.0.0.0", "MCP_HTTP_PORT": "8000", "MCP_HTTP_BEARER_TOKEN": "" } }

  说明

  • GHOSTFOLIO_URL 与 GHOSTFOLIO_TOKEN 是与 Ghostfolio 实例的对接所必需的。
  • 速率限制、只读模式、禁用标签等行为通过相应的环境变量配置。
  • MCP_TRANSPORT 指定传输协议，STDIO 为默认本地通信，SSE/HTTP 可通过相应的主机端口对外暴露。

• 基本使用方法

  • 启动服务：在具备上述环境变量的环境中运行服务器（如执行 ghostfolio-mcp 或 python run_server.py）。
  • 客户端连接：使用 MCP 客户端按 JSON-RPC 调用格式向服务器发送请求，例如查询账户、投资组合、市场数据等工具的调用，请参考客户端的工具调用文档。
  • 访问控制与安全：若开启了 HTTP Bearer Token，请在客户端请求头中提供 Authorization: Bearer <token>。
  • 传输与部署：按需配置 STDIO、SSE、或 HTTP 传输方式，并根据需要对主机与端口进行暴露。