unified-finance-mcp

One MCP server for finance data: Yahoo Finance, TradingView, FMP, Alpha Vantage, marketaux, Futu OpenD and the Kimi Datasource meta-source behind a single tool surface, with market-aware auto-routing across sources.

Features

Data sources: Yahoo Finance · TradingView · FMP · Alpha Vantage · marketaux · Futu OpenD · Kimi Datasource (tianyancha CN company data, World Bank / IMF macro series, SEC EDGAR, S&P Capital IQ, gildata screener data, and more).

The unified tools accept futu (HK.00700), Yahoo (0700.HK, COMI.CA) and TradingView (EGX:COMI) symbol forms; bare tickers default to US.

Install

Requires Python ≥ 3.10.

uvx unified-finance-mcp          # ephemeral run (uv)
pipx install unified-finance-mcp # persistent install
pip install unified-finance-mcp  # classic install

The console entry point is unified-finance-mcp. By default it serves stdio (MCP client spawns it directly); --transport http serves streamable HTTP with a /health endpoint.

Configuration

All configuration is via environment variables. The server's own knobs use the FINANCE_MCP_* prefix; third-party credentials keep their vendor names. Every key is optional — each provider activates only when its credential is present, and auto-routing skips unavailable sources.

Core (all providers)

FMP

Alpha Vantage

marketaux

Kimi Datasource

Auth resolution order: KIMI_PROXY_URL → KIMI_ACCESS_TOKEN → KIMI_AUTH_FILE. Exactly one way needs to be configured for the kimi tools to activate.

Futu OpenD (inherited from futu-opend-mcp)

Client configuration

Claude Code

# stdio (default transport)
claude mcp add finance -- uvx unified-finance-mcp

# with environment, e.g. your API keys + rotator endpoints
claude mcp add finance \
  --env FMP_API_KEY=<your-fmp-key> \
  --env FMP_BASE_URL=http://api-key-rotator:8788/fmp \
  --env KIMI_PROXY_URL=http://kimi-datasource-proxy:8788/coding/v1/tools \
  --env FUTU_OPEND_HOST=192.168.1.10 \
  -- uvx unified-finance-mcp

# streamable HTTP mode (server started with --transport http)
claude mcp add --transport http finance http://127.0.0.1:8000/mcp

claude_desktop_config.json

{
  "mcpServers": {
    "finance": {
      "command": "uvx",
      "args": ["unified-finance-mcp"],
      "env": {
        "FMP_API_KEY": "<your-fmp-key>",
        "FMP_BASE_URL": "http://api-key-rotator:8788/fmp",
        "ALPHAVANTAGE_API_KEY": "<your-av-key>",
        "KIMI_PROXY_URL": "http://kimi-datasource-proxy:8788/coding/v1/tools",
        "FUTU_OPEND_HOST": "127.0.0.1"
      }
    }
  }
}

Streamable HTTP (any MCP client)

Start the server:

FINANCE_MCP_TRANSPORT=http unified-finance-mcp --port 8000
# or: unified-finance-mcp --transport http --port 8000

then connect to http://127.0.0.1:8000/mcp (health probe at http://127.0.0.1:8000/health).

Migrating from mcpo (5 servers → 1)

Replace the mcpo-aggregated stack — futu-opend, yfinance, tradingview (wrapped through mcpo) plus FMP and Alpha Vantage over streamable HTTP — with a single unified-finance-mcp entry.

Before (mcpo config, five servers):

{
  "mcpServers": {
    "futu":        { "command": "uvx", "args": ["futu-opend-mcp"] },
    "yfinance":    { "command": "mcpo", "args": ["--config", "/path/to/yfinance-mcp.json"] },
    "tradingview": { "command": "mcpo", "args": ["--config", "/path/to/tradingview-mcp.json"] },
    "fmp":         { "type": "sse", "url": "http://localhost:8788/fmp" },
    "alphavantage":{ "type": "sse", "url": "http://localhost:8788/alphavantage" }
  }
}

After:

{
  "mcpServers": {
    "finance": {
      "command": "uvx",
      "args": ["unified-finance-mcp"],
      "env": {
        "FMP_API_KEY": "<your-fmp-key>",
        "FMP_BASE_URL": "http://api-key-rotator:8788/fmp",
        "ALPHAVANTAGE_API_KEY": "<your-av-key>",
        "MARKETAUX_API_TOKEN": "<your-marketaux-token>",
        "KIMI_PROXY_URL": "http://kimi-datasource-proxy:8788/coding/v1/tools",
        "FUTU_OPEND_HOST": "127.0.0.1"
      }
    }
  }
}

The same credentials carry over; yfinance and tradingview need no key (they are backed by yfinance and tradingview-ta/tradingview-screener in-process, which also removes the Python ≥3.14 wrapper constraint mcpo hit).

Tool quick reference

Plus the 53 mounted futu-opend-mcp tools (get_snapshot, get_kline, futu_get_option_chain, get_capital_flow, …) for HK/CN/US depth from OpenD.

Development

pip install -e ".[dev]"
ruff check .                        # lint
pytest -q -m "not integration"      # unit suite (integration marker needs live APIs/OpenD)

Layout: src/unified_finance_mcp/ — providers/ (Yahoo, TradingView, FMP, Alpha Vantage, marketaux, Futu bridge, Kimi), tools/ (the 14 tool modules registered from ALL_MODULES), config.py (env Settings), http.py (polite per-host rate-limited client).

Release process

1. Push your changes to main and confirm CI is green (ruff + pytest).
2. On PyPI, add this repository as a pending trusted publisher (one-time setup).
3. Tag and push:

git tag v0.1.0 && git push origin v0.1.0

publish.yml builds the wheel/sdist and publishes to PyPI via OIDC trusted publishing (no tokens stored in the repo).

License

MIT