Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Stockflow MCP Server show me AAPL stock data"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server that provides comprehensive financial data and analysis tools using Yahoo Finance. This is a JavaScript/Node.js port of the original Python version.
Real-time Stock Data: Get current prices, market data, and company information
Historical Data: Fetch historical price data with technical indicators
Technical Analysis: Built-in SMA, EMA, RSI, MACD calculations
Options Chain: Access options data with Greeks and analysis
Financial Statements: Quarterly income, balance sheet, and cash flow data
Analyst Data: Recommendations and price targets
Related MCP server: Finance MCP Server
Node.js 18.0.0 or higher
npm or yarn package manager
Clone or create your project directory:
mkdir stockflow-mcp-server
cd stockflow-mcp-serverInitialize the project and install dependencies:
npm init -y
npm install @modelcontextprotocol/sdk yahoo-finance2 technicalindicators
npm install --save-dev @types/nodeCopy the server code to index.js
Update your package.json to include "type": "module" for ES modules support
node index.jsOr if you've set up the npm script:
npm startget_stock_data_v2)Get comprehensive stock information including market data, valuation metrics, and optional financials.
Parameters:
symbol (required): Stock ticker symbol (e.g., "AAPL")
include_financials (optional): Include quarterly financial statements
include_analysis (optional): Include analyst recommendations
include_calendar (optional): Include calendar events
Example:
{
"symbol": "AAPL",
"include_financials": true,
"include_analysis": true
}get_historical_data_v2)Fetch historical price data with technical indicators.
Parameters:
symbol (required): Stock ticker symbol
period (required): Time period (1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max)
interval (optional): Data interval (1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo)
prepost (optional): Include pre/post market data
Example:
{
"symbol": "TSLA",
"period": "1y",
"interval": "1d"
}get_options_chain_v2)Access options chain data with analysis.
Parameters:
symbol (required): Stock ticker symbol
expiration_date (optional): Specific expiration date (YYYY-MM-DD)
include_greeks (optional): Include options Greeks
Example:
{
"symbol": "SPY",
"expiration_date": "2024-03-15"
}The server automatically calculates the following technical indicators for historical data:
Simple Moving Average (SMA): 20-day and 50-day
Exponential Moving Average (EMA): 12-day and 26-day
MACD: Moving Average Convergence Divergence with signal line
RSI: Relative Strength Index (14-day period)
The server includes comprehensive error handling with:
Retry Logic: Automatic retries for API failures
Validation: Input parameter validation
Logging: Detailed logging to stockflow_v2.log
Graceful Degradation: Continues operation even if optional data fails
Logs are written to stderr only to avoid interfering with MCP's JSON-RPC communication on stdout. The server automatically suppresses console output from the yahoo-finance2 library to prevent protocol corruption.
Note: Due to MCP communication requirements, no log files are created. All logging output goes to stderr and will be visible in your terminal when running the server directly.
While not required, you can optionally set these environment variables:
NODE_ENV: Set to 'development' for more verbose logging
The server automatically suppresses console.log, console.warn, and console.info output from dependencies (particularly yahoo-finance2) that could interfere with MCP communication. Only critical errors are redirected to stderr.
This server is designed to work with MCP-compatible clients like:
Claude Desktop
Cursor IDE
Other MCP-enabled applications
Add this server to your MCP client configuration. Example for Claude Desktop:
{
"mcpServers": {
"stockflow": {
"command": "node",
"args": ["/path/to/your/stockflow-server/index.js"]
}
}
}This JavaScript version maintains API compatibility with the Python version while making these adaptations:
Library Changes:
yfinance → yahoo-finance2
pandas → Native JavaScript arrays and objects
mcp.server → @modelcontextprotocol/sdk
Technical Indicators:
Uses technicalindicators library instead of manual pandas calculations
Same calculation methods and periods for compatibility
Error Handling:
JavaScript Promises instead of Python async/await syntax
Similar retry logic and error classification
Data Formats:
JSON-compatible data structures throughout
ISO date formatting for consistency
Console Output Management:
Automatic suppression of library debug output to prevent MCP protocol interference
All logging redirected to stderr to maintain clean stdout for JSON-RPC communication
Filesystem Independence:
No log file creation (logs to stderr only)
Works in read-only and sandboxed environments
Module Not Found Errors: Ensure you have Node.js 18+ and all dependencies installed
API Rate Limits: Yahoo Finance may rate limit requests; the server includes retry logic
Network Timeouts: Check your internet connection if API calls fail consistently
JSON Parse Errors in MCP Client: This usually indicates console output is interfering with MCP communication - the server now automatically suppresses such output
Read-Only Filesystem Errors: The server no longer attempts to write log files and should work in sandboxed environments
The server logs to stderr by default. To see more detailed output, run your MCP client with verbose logging enabled, or run the server directly to see stderr output:
node index.jsIf you see JSON parsing errors in your MCP client logs:
Ensure no other applications are writing to stdout
Verify the server is running with the console output suppression (built-in)
Check that you're using the latest version of the server code
Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request
MIT License - see LICENSE file for details
Based on the original Python stockflow server
Uses Yahoo Finance data via the yahoo-finance2 library
Built with the official MCP TypeScript/JavaScript SDK
Technical indicators powered by technicalindicators library
Get historical price data with technical indicators
| Name | Required | Description | Default |
|---|---|---|---|
| period | Yes | Time period (1d, 5d, 1mo, 3mo, 6mo, 1y, 2y, 5y, 10y, ytd, max) | |
| symbol | Yes | Stock ticker symbol | |
| prepost | No | Include pre and post market data | |
| interval | No | Data interval (1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, 1d, 5d, 1wk, 1mo, 3mo) | 1d |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It only states the basic action without mentioning what technical indicators are included, whether they are calculated or pre-existing, data adjustment policies, or any rate limits. No behavioral traits are disclosed beyond the generic verb.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single clear sentence with zero wasted words. It is front-loaded with the core purpose and quickly readable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has no output schema and no annotations, so the description must compensate by explaining what 'technical indicators' means and what the response looks like. It does not, leaving significant ambiguity about the returned data structure and indicator specifics.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for all four parameters, so the schema already documents each parameter's meaning. The description adds no additional parameter context, earning the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Get' and resource 'historical price data' with 'technical indicators', clearly distinguishing it from siblings like get_stock_data_v2 and get_options_chain_v2. The 'historical' qualifier provides clear scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. It does not mention that get_stock_data_v2 might be for current data or how historical data with indicators differs. There is no explicit context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get options chain data with advanced greeks and analysis
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Stock ticker symbol | |
| include_greeks | No | Include options greeks | |
| expiration_date | No | Options expiration date (YYYY-MM-DD) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the transparency burden. It only says 'Get' and mentions 'advanced greeks and analysis', without disclosing output format, limitations, or whether it is purely read-only. This leaves significant behavioral aspects unexplained.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, compact sentence with no unnecessary words. It front-loads the core purpose ('Get options chain data') and adds a brief qualifier. It is appropriately concise, though slightly vague on 'analysis'.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description should clarify what is returned and behavior around optional parameters like expiration_date. It only states 'options chain data' and 'greeks', leaving the overall context incomplete for an agent to predict tool behavior reliably.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers all three parameters with descriptions, and the tool description adds minimal extra semantics beyond hinting at greeks (aligned with include_greeks). This matches the baseline of 3 for high schema coverage, as the description does not compensate for any gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action 'Get' and the specific resource 'options chain data', with additional detail on 'advanced greeks and analysis'. This definitively distinguishes it from sibling tools like get_stock_data_v2 and get_historical_data_v2, which focus on different data types.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance is provided on when to use this tool versus alternatives, but the resource type ('options chain') implies its usage context. It lacks any exclusions or mentions of when not to use it, so it only reaches implied usage level per the rubric.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get comprehensive stock data including financials, analyst ratings, and calendar events
| Name | Required | Description | Default |
|---|---|---|---|
| symbol | Yes | Stock ticker symbol | |
| include_analysis | No | Include analyst data | |
| include_calendar | No | Include calendar events | |
| include_financials | No | Include quarterly financials |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden of behavioral disclosure. It clearly states what data is included, but does not disclose return format, default behavior (e.g., whether all categories are included by default), or any side effects. It is adequate for a read-only 'get' tool but not rich in caveats or context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, front-loaded sentence that immediately identifies the tool's purpose and scope. Every phrase earns its place ('comprehensive stock data' plus three specific categories) with zero redundancy. Excellent conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (four parameters, no output schema), the description sufficiently conveys what the tool returns by listing the three data categories. It could be more complete by noting behavior when include flags are missing, but the schema already covers parameters. Overall, enough context for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema fully documents each parameter. The description adds no new parameter-level meaning beyond listing categories already covered by the schema (financials, ratings, calendar). Baseline 3 is appropriate because the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and clearly defines the resource ('comprehensive stock data') plus the included categories (financials, analyst ratings, calendar events). This distinguishes it from siblings like get_historical_data_v2 and get_options_chain_v2, which focus on price history and options chains respectively.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'comprehensive stock data' implies this is the go-to tool for financials, ratings, and calendar info, but the description does not explicitly state when to use it over siblings or when not to use it. No alternative tools are mentioned, leaving usage context to the reader's inference from sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0get_historical_data_v2get_options_chain_v2get_stock_data_v2Scored across 3 tools
Each tool serves a clearly distinct purpose: comprehensive stock data, historical prices with technical indicators, and options chains. There is no overlap or ambiguity between them.
All tool names follow a consistent pattern: get_<data_type>_v2 with snake_case and a unified version suffix. The naming is predictable and easy to navigate.
With 3 tools, the server is on the lower end of the typical range, but each tool is broad enough (covering financials, historical data, and options) to feel appropriately scoped. A slightly larger set could be justified, but this is not a serious issue.
The tool set covers the core data needs for stock analysis: current/fundamental data, historical trends, and options. Missing features like symbol search or news are notable but not critical for the apparent purpose, as the existing tools are comprehensive within their domains.
Scrape stock quotes, historical prices, and financial statements from Yahoo Finance.
Real-time stock quotes and technical signals: RSI, MACD, SMA crossovers via Yahoo Finance.
Live market data, financial analysis, and portfolio research tools across 10,000+ tickers.
Analyze stocks with summaries, price targets, and analyst recommendations. Track SEC filings, divi…
