Stockflow Server

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.

Features

• 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

Installation

Prerequisites

• Node.js 18.0.0 or higher
• npm or yarn package manager

Setup

1. Clone or create your project directory:

   mkdir stockflow-mcp-server
   cd stockflow-mcp-server
   

2. Initialize the project and install dependencies:

   npm init -y
   npm install @modelcontextprotocol/sdk yahoo-finance2 technicalindicators
   npm install --save-dev @types/node
   

3. Copy the server code to index.js

4. Update your package.json to include "type": "module" for ES modules support

Usage

Running the Server

node index.js

Or if you've set up the npm script:

npm start

Available Tools

1. Get Stock Data (get_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
}

2. Get Historical Data (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"
}

3. Get Options Chain (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"
}

Technical Indicators

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)

Error Handling

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

Configuration

Logging

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.

Environment Variables

While not required, you can optionally set these environment variables:

• NODE_ENV: Set to 'development' for more verbose logging

Console Output Suppression

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.

MCP Integration

This server is designed to work with MCP-compatible clients like:

• Claude Desktop
• Cursor IDE
• Other MCP-enabled applications

Client Configuration

Add this server to your MCP client configuration. Example for Claude Desktop:

{
  "mcpServers": {
    "stockflow": {
      "command": "node",
      "args": ["/path/to/your/stockflow-server/index.js"]
    }
  }
}

Differences from Python Version

This JavaScript version maintains API compatibility with the Python version while making these adaptations:

1. Library Changes:

   • yfinance → yahoo-finance2
   • pandas → Native JavaScript arrays and objects
   • mcp.server → @modelcontextprotocol/sdk

2. Technical Indicators:

   • Uses technicalindicators library instead of manual pandas calculations
   • Same calculation methods and periods for compatibility

3. Error Handling:

   • JavaScript Promises instead of Python async/await syntax
   • Similar retry logic and error classification

4. Data Formats:

   • JSON-compatible data structures throughout
   • ISO date formatting for consistency

5. 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

6. Filesystem Independence:

   • No log file creation (logs to stderr only)
   • Works in read-only and sandboxed environments

Troubleshooting

Common Issues

1. Module Not Found Errors: Ensure you have Node.js 18+ and all dependencies installed
2. API Rate Limits: Yahoo Finance may rate limit requests; the server includes retry logic
3. Network Timeouts: Check your internet connection if API calls fail consistently
4. JSON Parse Errors in MCP Client: This usually indicates console output is interfering with MCP communication - the server now automatically suppresses such output
5. Read-Only Filesystem Errors: The server no longer attempts to write log files and should work in sandboxed environments

Debug Mode

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.js

MCP Communication Issues

If 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

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details

Acknowledgments

• 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