Name: 投资分析工具
Author: liqiqiii

使用说明

📈 投资MCP服务器

个人投资分析工具包——宏观经济数据、航运市场和油轮股票模型上下文协议.

🖥️ 实时仪表板

👉 liqiqiii.github.io/investment-mcp

仪表板在工作日通过GitHub Actions自动更新。在手机或桌面上打开它，即可通过交互式Plotly图表一览所有跟踪仪器。

报告	链接
完整仪表板	liqiqiii.github.io/investment-mcp
前线（FRO）	详细信息页面
DHT控股公司（DHT）	详细信息页面
国际航道（INSW）	详细信息页面
泰凯油轮（TNK）	详细信息页面
北美油轮（NAT）	详细信息页面
天蝎座油轮（STNG）	详细信息页面
TORM PLC	详细信息页面

宏观数据 （国债收益率、CPI、GDP）将出现一次免费FRED API密钥已配置。

概述

投资MCP服务器是一个与MCP兼容的服务器，可向任何MCP客户端（Claude Desktop、VS Code Copilot等）提供金融市场数据、交互式图表和精心策划的知识库。它专为跟踪以下情况的个人投资者而设计：

宏观指标 --通过FRED计算国债收益率、联邦基金利率、CPI和GDP。
油轮股票 --VLCC、苏伊士型油轮和成品油轮库存（前线、DHT、天蝎座油轮等）通过雅虎财经。
航运指数 --波罗的海干散货指数和波罗的海脏油轮指数。

数据按需获取，在SQLite中本地缓存，并可以呈现到部署到GitHub Pages的交互式Plotly仪表板中。

特性

11个MCP工具 用于数据检索、报告生成和知识管理
交互式绘图图表 --响应式、移动友好的HTML报告
每日数据 来自FRED、雅虎财经和航运市场的消息来源
自动部署GitHub Pages仪表板 查看投资组合概览
财务分析知识库 --策划VLCC分析、产量曲线等降价技能文件
对话自动摘要 --跨会话保存和搜索分析笔记
可作为独立二进制文件分发 通过PyInstaller
可扩展的提供者插件架构 --通过子类化添加新数据源 BaseProvider

快速开始

先决条件

Python 3.11或更高版本
A免费 FRED API密钥

安装

git clone https://github.com/liqiqiii/investment-mcp.git
cd investment-mcp
pip install -e .

配置

复制示例环境文件并填写API密钥：

cp .env.example .env

# .env
INVESTMENT_FRED_API_KEY=your_fred_api_key_here

跑

investment-mcp

服务器启动并重新通信标准 --将其连接到任何MCP客户端，如下所示。

MCP客户端配置

克劳德桌面版

添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "investment-mcp": {
      "command": "investment-mcp",
      "env": {
        "INVESTMENT_FRED_API_KEY": "your_fred_api_key_here"
      }
    }
  }
}

VS代码/GitHub副本

添加到您的VS代码 settings.json:

{
  "mcp": {
    "servers": {
      "investment-mcp": {
        "command": "investment-mcp",
        "env": {
          "INVESTMENT_FRED_API_KEY": "your_fred_api_key_here"
        }
      }
    }
  }
}

通用标准传输

任何支持stdio传输的MCP客户端都可以启动服务器：

{
  "command": "investment-mcp",
  "transport": "stdio",
  "env": {
    "INVESTMENT_FRED_API_KEY": "your_fred_api_key_here"
  }
}

提示： 如果您安装了 pip install -e .，the investment-mcp 入口点在您的路径上。否则，请使用可执行文件的完整路径或 python -m investment_mcp.server.

可用工具

#	工具	描述	必需参数
1	`list_instruments`	列出所有跟踪的仪器；可选择按类别筛选(`macro`, `stock`, `shipping`).	—
2	`get_historical_data`	获取仪器的历史时间序列数据。	`instrument_id`
3	`get_latest`	获取仪器的最新数据点。	`instrument_id`
4	`compare_instruments`	同一时间范围内多个仪器的标准化比较。	`instrument_ids`
5	`generate_report`	使用Plotly图表生成交互式HTML报告。	—
6	`generate_dashboard`	为所有跟踪的仪器生成一个完整的概览仪表板。	—
7	`get_knowledge`	按主题名称检索知识库文章。	`topic`
8	`list_knowledge`	列出所有可用的知识库文章。	—
9	`save_note`	将对话摘要或分析笔记另存为markdown。	`title`, `content`
10	`search_notes`	通过保存的分析笔记进行全文搜索。	`query`
11	`list_notes`	列出所有保存的笔记，包括日期、标题和标签。	—

仪器ID格式

仪器ID遵循以下模式 <provider>:<ticker>:

fred:DGS10      — 10-Year Treasury Yield (FRED)
stock:FRO       — Frontline PLC (Yahoo Finance)
shipping:BDI    — Baltic Dry Index (Shipping)

跟踪仪器

宏（FRED）

ID	名称	描述	单位
`fred:DGS10`	10年期国债收益率	固定到期10年期国库券利率	%
`fred:DGS30`	30年期国债收益率	30年期固定国债利率	%
`fred:DGS2`	2年期国债收益率	固定到期2年期国库券利率	%
`fred:DFF`	联邦基金利率	有效联邦基金利率	%
`fred:CPIAUCSL`	居民消费价格指数	城市居民消费物价指数	指数
`fred:GDP`	国内生产总值	美国GDP	十亿美元

油轮股票（雅虎财经）

ID	名称	描述	货币
`stock:FRO`	前线PLC	国际油轮运输	美元
`stock:DHT`	DHT控股	原油运输	美元
`stock:INSW`	国际海运	油轮运输	美元
`stock:TNK`	Teekay油轮	原油和成品油轮	美元
`stock:NAT`	北美油轮	苏伊士型油轮	美元
`stock:STNG`	Scorpio油轮	成品油轮运输	美元
`stock:EURN`	Euronav	原油油轮运输	美元
`stock:HAFN`	Hafnia	产品/化学品油轮（奥斯陆）	挪威克朗
`stock:TRMD`	TORM PLC	成品油轮运输	美元

航运指数

ID	名称	描述
`shipping:BDI`	波罗的海干散货运价指数
`shipping:BDIY`	波罗的海脏油轮指数	脏（原油）油轮运费

GitHub页面仪表板

实时仪表板位于 liqiqiii.github.io/investment-mcp --有关所有链接，请参阅此README的顶部。

运作原理

scripts/fetch_data.py 从所有提供者获取每日数据，并生成HTML报告到 docs/.
这 update_data.yml GitHub Actions工作流在每个工作日的UTC早上6点自动运行。
这 deploy_pages.yml 工作流部署 docs/ 每当GitHub页面发生变化时。

手动刷新

python scripts/fetch_data.py    # Fetch data + regenerate all reports
git add docs/ && git commit -m "Update dashboard" && git push

生成的报告是内嵌Plotly.js的自包含HTML文件，不需要服务器。

二进制分布

您可以使用PyInstaller将服务器打包为独立的可执行文件，这样它就可以在不安装Python的情况下运行。

构建

pip install -e ".[dev]"
pyinstaller --onefile --name investment-mcp src/investment_mcp/server.py

二进制文件输出到 dist/investment-mcp （或 dist\investment-mcp.exe 在Windows上）。

跑

# Linux / macOS
./dist/investment-mcp

# Windows
dist\investment-mcp.exe

将MCP客户端配置指向二进制路径，而不是 investment-mcp 入口点。

延伸

添加新的数据提供程序

创建提供者模块 在 src/investment_mcp/providers/:

from investment_mcp.providers.base import BaseProvider, Instrument

class MyProvider(BaseProvider):
    name: str = "myprovider"

    def list_instruments(self) -> list[Instrument]:
        return [
            Instrument(
                id="myprovider:TICKER",
                name="My Instrument",
                description="Description here",
                category="custom",
                provider="myprovider",
                ticker="TICKER",
                unit="USD",
            ),
        ]

    async def fetch(self, instrument, start_date, end_date):
        # Return a pandas DataFrame with a DatetimeIndex and value columns
        ...

注册提供商 在 server.py → _init_providers():

from investment_mcp.providers.my_provider import MyProvider
registry.register(MyProvider())

新仪器将自动出现在 list_instruments 并可用于所有数据和报告工具。

知识库

内置的知识库提供精心策划的分析框架作为MCP资源。通过以下方式访问它们 get_knowledge 工具或浏览 list_knowledge.

文件	主题
`vlcc_analysis.md`	VLCC船队动态、订单簿、报废趋势
`macro_indicators.md`	关键宏观指标及其对市场的影响
`shipping_market.md`	航运市场结构和费率驱动因素
`yield_curve_analysis.md`	收益率曲线解释和衰退信号
`tanker_company_profiles.md`	履带式油轮公司简介

知识文件存储在 src/investment_mcp/knowledge/ 并且也作为MCP资源在 knowledge:// URI方案。

项目结构

investment-mcp/
├── .env.example                  # Environment variable template
├── .github/workflows/            # CI / GitHub Pages deployment
├── docs/reports/                 # Generated HTML reports (gitkeep)
├── pyproject.toml                # Build config, dependencies, entry points
├── src/investment_mcp/
│   ├── __init__.py
│   ├── server.py                 # MCP server entry point & tool definitions
│   ├── config.py                 # Settings, instrument registry
│   ├── cache/
│   │   └── store.py              # SQLite data cache
│   ├── knowledge/                # Curated markdown skill files
│   │   ├── macro_indicators.md
│   │   ├── shipping_market.md
│   │   ├── tanker_company_profiles.md
│   │   ├── vlcc_analysis.md
│   │   └── yield_curve_analysis.md
│   ├── notes/                    # Saved analysis notes (user-generated)
│   ├── providers/
│   │   ├── base.py               # BaseProvider ABC & ProviderRegistry
│   │   ├── fred.py               # FRED economic data provider
│   │   ├── yahoo.py              # Yahoo Finance stock provider
│   │   └── shipping.py           # Shipping index provider
│   ├── reports/                  # Report generation (Plotly/Jinja2)
│   └── tools/
│       ├── data_tools.py         # list_instruments, get_historical_data, etc.
│       ├── report_tools.py       # generate_report, generate_dashboard
│       └── note_tools.py         # Knowledge & notes tools
└── tests/                        # pytest test suite

许可证

该项目根据 MIT许可证.