Professional finance research toolkit — backtesting (9 engines + benchmark comparison panel), factor analysis, Alpha Zoo (462 pre-built alphas across qlib158/alpha101/gtja191/academic/fundamental), options pricing, 89 finance skills, 30 multi-agent swarm teams, Trade Journal analyzer, and Shadow Account (extract → backtest → render) across 24 market-data sources (tushare, yfinance, okx, binance, akshare, baostock, tencent, mootdx, ccxt, futu, mt5, local, eastmoney, sina, stooq, yahoo, pykrx, india_broker, qveris, longbridge, plus optional-key finnhub/alphavantage/tiingo/fmp).
dependencies
{"python":">=3.11","pip":["vibe-trading-ai"]}
env
[{"name":"TUSHARE_TOKEN","description":"Tushare API token for China A-share data (optional — HK/US/crypto work without any key)","required":false},{"name":"OPENAI_API_KEY","description":"OpenAI-compatible API key — only needed for run_swarm (multi-agent teams). All other tools work without it.","required":false},{"name":"LANGCHAIN_MODEL_NAME","description":"LLM model name for run_swarm (e.g. deepseek/deepseek-v4-pro). Only needed if using run_swarm.","required":false}]
mcp
{"command":"vibe-trading-mcp","args":[]}
Vibe-Trading
Professional finance research toolkit with AI-powered backtesting (9 engines), multi-agent teams, 89 specialized skills, the Alpha Zoo (462 pre-built quantitative alphas across qlib158 / alpha101 / gtja191 / academic / fundamental with one-line CLI benchmarking), and the Shadow Account loop — extract your implicit trading rules from a journal, backtest them across A股/港股/美股/crypto, then see where they would have served you better.
Setup
pip install vibe-trading-ai
Package name vs commands: The PyPI package is vibe-trading-ai. Once installed, you get:
Command
Purpose
vibe-trading
Interactive CLI / TUI
vibe-trading serve
Launch FastAPI web server
vibe-trading-mcp
Start MCP server (for Claude Desktop, OpenClaw, Cursor, etc.)
Core research MCP tools work with zero API keys for HK/US/crypto. After pip install, backtesting, market data, factor analysis, options pricing, chart patterns, web search, document reading, trade journal analysis, shadow-account extraction/backtest/report, the Alpha Zoo (462 pre-built alphas), and all 89 skills are ready to use. IBKR tools require a local TWS / IB Gateway session; run_swarm requires an LLM key.
Feature
Key needed
When
HK/US equities & crypto
None
Always free (yfinance / stooq / yahoo + OKX)
China A-share data
None
Free via akshare / baostock / tencent / sina / eastmoney / mootdx fallback (TUSHARE_TOKEN optional for premium quality)
extract_shadow_strategy — distill 3-5 if-then rules that describe your profitable roundtrips.
run_shadow_backtest — backtest those rules across A/HK/US/crypto and compute delta-PnL vs your realized trades.
render_shadow_report — produce an HTML/PDF report (8 sections + charts) with today's matching signals.
scan_shadow_signals — list today's symbols that match your shadow's entry cadence (research only).
Backtesting
Create and run quantitative strategies across 9 engines (ChinaA, GlobalEquity, IndiaEquity, KoreaEquity, Crypto, ChinaFutures, GlobalFutures, Forex + options) with 24 market-data sources (auto-detect + ordered fallback):
HK/US equities via yfinance / stooq / yahoo (free, no API key); optionally via Longbridge historical OHLCV (longbridge, requires the optional SDK and LONGBRIDGE_APP_KEY / LONGBRIDGE_APP_SECRET / LONGBRIDGE_ACCESS_TOKEN). To force it for a run, set "source": "longbridge" in config.json.
India equities (NSE/BSE) via yahoo / yfinance using <SYMBOL>.NS (NSE, e.g. RELIANCE.NS) or <SCRIP>.BO (BSE, e.g. 500325.BO) — free, no API key. The IndiaEquityEngine models T+1 delivery, no overnight shorts (set allow_short for intraday), configurable circuit bands, 1-share lots, and the STT/stamp-duty/exchange/GST cost stack. Optionally back-fill from your live broker via the india_broker source (Shoonya/Dhan; requires broker login).
Korea equities (KRX: KOSPI/KOSDAQ) via pykrx using <CODE>.KS (KOSPI, e.g. 005930.KS) or <CODE>.KQ (KOSDAQ, e.g. 247540.KQ) — free, no API key (pip install "vibe-trading-ai[krx]"; yahoo/yfinance fallback needs no extra). pykrx serves daily bars only (an intraday request falls through to another source) and its adjusted series is Naver-backed rather than a verbatim KRX print. The KoreaEquityEngine models same-day round trips (no T+1), the ±30% daily price limit measured from the previous close and quantized to the KRX tick grid, tick-rounded fills, the 0.20% sell-side transaction tax (2026 rate), and 1-share lots. It is long-only: allow_short is refused, because KRX covered-short and uptick rules cannot be enforced on daily bars.
Cryptocurrency via OKX or CCXT/100+ exchanges (free, no API key)
China A-shares via AKShare / baostock / tencent / sina / eastmoney / mootdx (free, no API key) — TUSHARE_TOKEN optional for premium quality
Futures, forex, macro via AKShare (free, no API key)
HK & A-share equities via Futu (broker login required, optional)
Local CSV/parquet bars via the local loader (offline, no network)
Premium cross-market data via QVeris (optional API key)
Premium US data via optional-key finnhub / alphavantage / tiingo / fmp (graceful fallback to free sources)
Factors: the Alpha101 and QLib158 zoos are tagged for the equity_in and equity_kr universes, so they compute on NSE/BSE and KRX bars (the GTJA191 zoo stays China-only). Live/paper India trading uses the Shoonya / Dhan connectors (paper + read-only live; live order placement is structurally disabled because those brokers expose no paper/live switch).
Example workflow:
Use list_skills() to discover strategy patterns
Use load_skill("strategy-generate") for the strategy creation guide
Use write_file() to create config.json and code/signal_engine.py
Use backtest() to run and get metrics (Sharpe, return, drawdown, etc.)
fundamental (4 factors) — PIT-safe earnings yield, ROE, gross profitability, and asset growth from daily fundamental panels.
Each alpha ships with __alpha_meta__ (formula LaTeX + theme + universe + warmup + columns required), guarded by an AST purity gate + 300-row lookahead sentinel test. Use the vibe-trading alpha {list,show,bench,compare,export-manifest} CLI, the /alpha/* REST routes (browser at /alpha-zoo), or compose multi-factor signals via ZooSignalEngine.from_zoo(...).
Inspect QVeris tool schemas before executing (free)
QVERIS_API_KEY + paid mode
qveris_execute
Execute a QVeris capability; budget-bounded, may be billable
QVERIS_API_KEY + paid mode
web_search
Search the web via DuckDuckGo
None
read_url
Fetch web page as Markdown
None
read_document
Extract text from PDF/DOCX/XLSX/PPTX/images
None
write_file
Write files (config, strategy code)
None
read_file
Read file contents
None
analyze_trade_journal
Parse broker CSV → profile + behavior diagnostics
None
extract_shadow_strategy
Distill 3-5 if-then rules from profitable roundtrips
None
run_shadow_backtest
Multi-market backtest + delta-PnL attribution
None*
render_shadow_report
HTML/PDF shadow report (8 sections + charts)
None
scan_shadow_signals
Today's symbols matching the shadow's cadence
None
list_swarm_presets
List multi-agent team presets
None
run_swarm
Execute a multi-agent research team
LLM key
get_swarm_status
Poll swarm run status without blocking
None
get_run_result
Get final report and task summaries
None
list_runs
List recent swarm runs with metadata
None
reap_stale_runs
Finalize stale swarm runs
None
retry_run
Re-run a failed/stale swarm run
LLM key
trading_connections
List selectable connector profiles
None
trading_select_connection
Select the default connector profile
None
trading_check
Check connector readiness
Connector app/OAuth
trading_account
Read account summary from selected connector
Connector app/OAuth
trading_positions
Read positions from selected connector
Connector app/OAuth
trading_orders
Read open orders from selected connector
Connector app/OAuth
trading_quote
Read a quote snapshot from selected connector
Connector app/OAuth
trading_history
Read historical bars from selected connector
Connector app/OAuth
*A-share symbols require TUSHARE_TOKEN. HK/US/crypto are free. Trading connector rows use the selected connector profile, e.g. IBKR local TWS/Gateway or Robinhood MCP OAuth.
Quick Start
pip install vibe-trading-ai
That's it — no API keys needed for HK/US/crypto markets. Start using backtest, get_market_data, analyze_options, analyze_trade_journal, extract_shadow_strategy, web_search, the Alpha Zoo (vibe-trading alpha bench --zoo gtja191 --universe csi300 --period 2018-2025), and all 89 skills immediately.
Loading Tools from External MCP Servers
The built-in agent can load tools from your own external MCP servers in addition to its local toolset.
Note: This is the MCP client path — the opposite of the MCP plugin listed above. The plugin above makes Vibe-Trading's tools available to your agents. This section lets Vibe-Trading's own agent call tools from your servers.
Ordinary external MCP tools appear automatically in every vibe-trading run / vibe-trading chat call. They are injected after local tools under stable names: mcp_<server>_<tool>. Live-broker MCP servers are consumed through the connector-scoped trading_* tools instead of exposing raw mcp_<broker>_* tools to the agent.
Official IBKR MCP read-only probe
Add Interactive Brokers' official MCP endpoint as a read-only external server:
Authorize it with vibe-trading connector authorize ibkr-live-official-mcp-readonly. The wildcard is accepted
only for this mcp.read probe. Generic trading_account and trading_positions
calls stay disabled until IBKR publishes stable read tool names that Vibe-Trading
can map safely; mcp.write requires an explicit tool allowlist and live
order-guard handling. If IBKR issues a pre-registered OAuth client, add
clientId and clientSecret inside auth.
Trading connector profiles
The public trading surface is connector-first. Choose a connector profile, then
paper/live is just an attribute under that connector.
Default ports are TWS paper 7497, IB Gateway paper 4002, TWS live-readonly
7496, and IB Gateway live-readonly 4001.
Config fields
Field
Required
Default
Description
type
stdio: no, HTTP: yes
inferred only for stdio
Transport type. Use sse or streamableHttp for URL-based servers.
command
stdio: yes
—
Executable to launch
args
no
[]
Command arguments
env
no
{}
Extra env vars for the subprocess
url
HTTP: yes
—
Remote SSE / streamable HTTP endpoint URL
headers
no
{}
Extra HTTP headers for SSE / streamable HTTP servers
toolTimeout
no
30
Seconds before a tool call is cancelled
enabledTools
no
["*"]
Allowlist of remote tool names. ["*"] enables all
For URL-based transports, type is required. The agent no longer guesses between SSE and streamable HTTP from the URL suffix.
Per-session override (API)
Security — disabled by default.mcpServers defines subprocess command/args/env and is therefore restricted to operator-level trust. API callers cannot inject MCP server definitions through POST /sessions unless the server operator explicitly opts in.
To enable session-level MCP injection, set the environment variable on the server before starting the agent:
export ALLOW_SESSION_MCP_SERVERS=1
With the opt-in active, pass mcpServers inside session.config to extend or replace the global config for that session only:
Without ALLOW_SESSION_MCP_SERVERS=1, any mcpServers key in session.config is silently stripped before config loading. The global operator config on disk (~/.vibe-trading/agent.json) is always respected regardless of this flag.
v1 limits
Transport: stdio, SSE, and streamable HTTP.
Execution: serial only. MCP tools never enter the parallel readonly path.
Surfaces: tools only. Resources and prompts are not exposed.
Swarm: MCP tools are excluded from Swarm worker registries in v1.
Hot reload: not supported. Restart the process to pick up config changes.
Failure handling
Case
Behavior
Missing config file
falls back to empty config — no MCP servers loaded
Invalid config file
logs a warning and falls back to empty config
Server fails to start
that server is skipped; local tools and other servers still load
Tool call times out
returns a normalized error payload instead of raising
Backtest AAPL with MACD crossover strategy (fast=12, slow=26, signal=9) for 2024
Analyze my trade journal and build a Shadow Account:
Call analyze_trade_journal on ~/Downloads/tonghuashun.csv, then extract_shadow_strategy with min_support=3, then run_shadow_backtest for the last year, then render_shadow_report.
Run an investment committee review:
Use run_swarm with investment_committee preset to evaluate NVDA. Variables: target=NVDA.US, market=US
Factor analysis on CSI 300:
Run factor_analysis on CSI 300 stocks using pe_ttm factor from 2023 to 2024
Options analysis:
Use analyze_options: spot=100, strike=105, 90 days, vol=25%, rate=3%
Multi-leg options payoff:
Use analyze_options_payoff for a 95/105 bull call spread at spot 100 with 30 days remaining: long one 95 call at premium 8, short one 105 call at premium 3, multiplier 100, commission rate 0.001.
