Stock Tool

Stock Tool MCP Server provides a powerful bridge between AI agents and real-time financial data. It offers multi-source market data, professional technical analysis, deep fundamental research, and smart aggregation tools to empower you to query data, compute indicators, and generate insightful market summaries directly from an MCP client.

How to use

You can use the MCP server with an MCP client to access real-time market data, run technical analyses, fetch fundamental information, and obtain comprehensive market snapshots. Set up your MCP client to connect via either the HTTP interface or the stdio channel, depending on your integration needs. The HTTP mode is suitable for testing, web apps, or remote consumption, while stdio mode enables low-latency, local integration with AI agents.

How to install

Prerequisites: Python 3.10+, Redis is optional for caching.

# 1. Clone the repository
git clone https://github.com/yourusername/stock-tool-mcp.git
cd stock-tool-mcp

# 2. Create and activate a Conda environment
# Create Python 3.11.14 environment
conda create -n stock-mcp python=3.11.14

# Activate the environment
conda activate stock-mcp

# 3. Install dependencies
pip install -r requirements.txt

# 4. Configuration
cp .env.example .env
# Edit .env to add your API keys as needed

Optional environment variables for data sources can be configured in the .env file. You can enable or disable data sources such as Tushare, Finnhub, and FRED, and provide corresponding API keys if you plan to use them.

Start the MCP server in one of the supported modes: HTTP server or stdio. Choose the mode that best fits your workflow.

# HTTP server (Streamable HTTP mode) - standard run
export MCP_TRANSPORT=streamable-http
python -m uvicorn src.server.app:app --host 0.0.0.0 --port 9898

# HTTP server with hot reload (development)
MCP_TRANSPORT=streamable-http python -m uvicorn src.server.app:app --reload --port 9898

# STDIO mode - local AI agent integration
bash start_stock_mcp_stdio.sh

# Manual start (alternative)
conda activate stock-mcp
python -c "import src.server.mcp.server as m; m.create_mcp_server().run(transport='stdio')"

Notes on configuration and modes

Two primary transport modes are supported: Streamable HTTP and stdio. Streamable HTTP exposes an HTTP API for remote clients and is suitable for production deployments. Stdio uses standard input/output for direct communication with local AI agents, offering lower latency and simpler integration without a network port.

Additional configuration details

When starting in HTTP mode, you can direct clients to the MCP server URL (for example, http://localhost:9898) and use the available tools through the HTTP API. In stdio mode, you can integrate with local AI agents by running the provided startup script or by invoking the Python startup command shown above.

Test and validation

You can verify the setup by performing a quick test that lists available tools and calls a few endpoints. Use the provided test script for an MCP+REST sanity check and generate OpenAPI documentation for tooling and testing.

Security and maintenance tips

Keep API keys in the .env file and restrict access to the MCP server. Regularly update dependencies and monitor data source availability. If a data source is disabled due to missing credentials, the server will automatically fall back to free alternatives to ensure uninterrupted service.

Available tools

search_assets

Search for stocks, crypto, or ETFs by name or ticker with example parameters like query and limit.

get_kline_data

Fetch OHLCV data for a specified symbol and date range.

get_technical_indicators

Compute technical indicators such as RSI, MACD, Bollinger Bands, and more.

get_financial_reports

Retrieve revenue and net income data for a symbol.

get_mainbz_info

Return main business composition for a symbol.

get_shareholder_info

Provide shareholder information for a symbol.

get_dividend_info

Show dividend history for a symbol.

get_money_flow

Analyze money flow for a stock over a number of days.

get_north_bound_flow

Show northbound capital flow over a period.

get_macro_data

Fetch macro indicators such as CPI, PPI, M2, GDP.

perform_deep_research

One-shot tool to fetch price, history, fundamentals, and recent news for a symbol.

get_market_report

Provide a comprehensive snapshot of the current market status.