convez.ai
MCP ServerFinanceiroIntermediário
liqiqiii

Investment MCP Server

liqiqiii/investment-mcp

Análise de investimentos e mercados de navegação via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP para análise de investimentos pessoais com dados de macroeconomia, mercados de navegação e ações de navios-tanque. Integra feeds do FRED, Yahoo Finance e índices de navegação em um dashboard interativo com gráficos Plotly.

Instalação

$npx convez-ai liqiqiii/investment-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 2 dias
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Monitorar indicadores macroeconômicos em tempo real
  • Acompanhar ações de navegação de navios-tanque (VLCC, Suezmax)
  • Gerar relatórios interativos e dashboards de portfólio
  • Consultar dados de índices de navegação (BDI, BDTI)

Veredito

Ferramenta sólida e especializada para investidores que rastreiam mercados de navegação e macro. O design modular (11 tools MCP, cache SQLite, dashboards Plotly) é bem executado. Audiência nicho, mas solução completa para o propósito.

README

A tradução para o português deste README ainda está na fila.

📈 Investment MCP Server

Personal investment analysis toolkit — macroeconomic data, shipping markets, and tanker equities via the Model Context Protocol.

Python 3.11+ License: MIT MCP


🖥️ Live Dashboard

👉 liqiqiii.github.io/investment-mcp

The dashboard updates automatically on weekdays via GitHub Actions. Open it on your phone or desktop for an at-a-glance view of all tracked instruments with interactive Plotly charts.

ReportLink
Full Dashboardliqiqiii.github.io/investment-mcp
Frontline (FRO)Detail page
DHT Holdings (DHT)Detail page
International Seaways (INSW)Detail page
Teekay Tankers (TNK)Detail page
Nordic American Tankers (NAT)Detail page
Scorpio Tankers (STNG)Detail page
TORM PLC (TRMD)Detail page

Macro data (Treasury yields, CPI, GDP) will appear once a free FRED API key is configured.


Overview

Investment MCP Server is an MCP-compatible server that surfaces financial market data, interactive charting, and a curated knowledge base to any MCP client (Claude Desktop, VS Code Copilot, etc.). It is designed for individual investors who track:

  • Macro indicators — Treasury yields, the Fed Funds Rate, CPI, and GDP via FRED.
  • Tanker equities — VLCC, Suezmax, and product tanker stocks (Frontline, DHT, Scorpio Tankers, and more) via Yahoo Finance.
  • Shipping indices — Baltic Dry Index and Baltic Dirty Tanker Index.

Data is fetched on demand, cached locally in SQLite, and can be rendered into interactive Plotly dashboards deployed to GitHub Pages.


Features

  • 11 MCP tools for data retrieval, report generation, and knowledge management
  • Interactive Plotly charts — responsive, mobile-friendly HTML reports
  • Daily data from FRED, Yahoo Finance, and shipping market sources
  • Auto-deployed GitHub Pages dashboard for at-a-glance portfolio views
  • Financial analysis knowledge base — curated markdown skill files on VLCC analysis, yield curves, and more
  • Conversation auto-summarization — save and search analysis notes across sessions
  • Distributable as a standalone binary via PyInstaller
  • Extensible provider plugin architecture — add new data sources by subclassing BaseProvider

Quick Start

Prerequisites

Install

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

Configure

Copy the example environment file and fill in your API key:

cp .env.example .env
# .env
INVESTMENT_FRED_API_KEY=your_fred_api_key_here

Run

investment-mcp

The server starts and communicates over stdio — connect it to any MCP client as shown below.


MCP Client Configuration

Claude Desktop

Add to your claude_desktop_config.json:

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

VS Code / GitHub Copilot

Add to your VS Code settings.json:

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

Generic stdio Transport

Any MCP client that supports the stdio transport can launch the server:

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

Tip: If you installed with pip install -e ., the investment-mcp entry point is on your PATH. Otherwise, use the full path to the executable or python -m investment_mcp.server.


Available Tools

#ToolDescriptionRequired Params
1list_instrumentsList all tracked instruments; optionally filter by category (macro, stock, shipping).—
2get_historical_dataFetch historical time-series data for an instrument.instrument_id
3get_latestGet the most recent data point for an instrument.instrument_id
4compare_instrumentsNormalized comparison of multiple instruments over the same time range.instrument_ids
5generate_reportGenerate an interactive HTML report with Plotly charts.—
6generate_dashboardGenerate a full overview dashboard for all tracked instruments.—
7get_knowledgeRetrieve a knowledge-base article by topic name.topic
8list_knowledgeList all available knowledge-base articles.—
9save_noteSave a conversation summary or analysis note as markdown.title, content
10search_notesFull-text search through saved analysis notes.query
11list_notesList all saved notes with dates, titles, and tags.—

Instrument ID Format

Instrument IDs follow the pattern <provider>:<ticker>:

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

Tracked Instruments

Macro (FRED)

IDNameDescriptionUnit
fred:DGS1010-Year Treasury YieldConstant maturity 10-year Treasury ratepercent
fred:DGS3030-Year Treasury YieldConstant maturity 30-year Treasury ratepercent
fred:DGS22-Year Treasury YieldConstant maturity 2-year Treasury ratepercent
fred:DFFFederal Funds RateEffective federal funds ratepercent
fred:CPIAUCSLConsumer Price IndexCPI for All Urban Consumersindex
fred:GDPGross Domestic ProductU.S. GDPbillions USD

Tanker Stocks (Yahoo Finance)

IDNameDescriptionCurrency
stock:FROFrontline PLCInternational tanker shippingUSD
stock:DHTDHT HoldingsCrude oil transportationUSD
stock:INSWInternational SeawaysTanker shippingUSD
stock:TNKTeekay TankersCrude and product tankersUSD
stock:NATNordic American TankersSuezmax crude oil tankersUSD
stock:STNGScorpio TankersProduct tanker shippingUSD
stock:EURNEuronavCrude oil tanker shippingUSD
stock:HAFNHafniaProduct/chemical tankers (Oslo)NOK
stock:TRMDTORM PLCProduct tanker shippingUSD

Shipping Indices

IDNameDescription
shipping:BDIBaltic Dry IndexComposite dry-bulk shipping rate index
shipping:BDIYBaltic Dirty Tanker IndexDirty (crude-oil) tanker freight rates

GitHub Pages Dashboard

The live dashboard is at liqiqiii.github.io/investment-mcp — see the top of this README for all links.

How It Works

  1. scripts/fetch_data.py pulls daily data from all providers and generates HTML reports into docs/.
  2. The update_data.yml GitHub Actions workflow runs this automatically every weekday at 6 AM UTC.
  3. The deploy_pages.yml workflow deploys docs/ to GitHub Pages whenever it changes.

Manual Refresh

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

Generated reports are self-contained HTML files with embedded Plotly.js — no server required.


Binary Distribution

You can package the server as a standalone executable using PyInstaller so it runs without a Python installation.

Build

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

The binary is output to dist/investment-mcp (or dist\investment-mcp.exe on Windows).

Run

# Linux / macOS
./dist/investment-mcp

# Windows
dist\investment-mcp.exe

Point your MCP client configuration at the binary path instead of the investment-mcp entry point.


Extending

Adding a New Data Provider

  1. Create a provider module in 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
        ...
  1. Register the provider in server.py → _init_providers():
from investment_mcp.providers.my_provider import MyProvider
registry.register(MyProvider())

The new instruments will automatically appear in list_instruments and be available to all data and report tools.


Knowledge Base

The built-in knowledge base provides curated analysis frameworks as MCP resources. Access them with the get_knowledge tool or browse via list_knowledge.

FileTopic
vlcc_analysis.mdVLCC fleet dynamics, order book, scrapping trends
macro_indicators.mdKey macro indicators and their market impact
shipping_market.mdShipping market structure and rate drivers
yield_curve_analysis.mdYield curve interpretation and recession signals
tanker_company_profiles.mdProfiles of tracked tanker companies

Knowledge files are stored in src/investment_mcp/knowledge/ and are also exposed as MCP resources under the knowledge:// URI scheme.


Project Structure

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

License

This project is licensed under the MIT License.

Ver o original no GitHub

Bom para

Relacionados