Yahoo Finance MCP Server

Use the following commands to maintain code quality:

Linting and Formatting:

uv run ruff check .
uv run ruff format .

Type Checking:

uv run ty check src tests

Running Tests:

uv run pytest -v -s --cov=src tests

To run from a local clone, first clone the repository and synchronize dependencies using uv:

git clone https://github.com/narumiruna/yfinance-mcp.git
cd yfinance-mcp
uv sync

Then, add the following to your MCP client configuration, ensuring you replace /path/to/yfinance-mcp with the absolute path to your local repository directory:

{
  "mcpServers": {
    "yfmcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/yfinance-mcp",
        "yfmcp"
      ]
    }
  }
}

You can run the server in a containerized environment using Docker. Add this configuration to your MCP client settings:

{
  "mcpServers": {
    "yfmcp": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "narumi/yfinance-mcp"]
    }
  }
}

To contribute to the project, ensure you have Python ≥ 3.12 and uv installed. Set up the development environment by running:

uv sync --extra dev

The recommended way to run the Yahoo Finance MCP server is using uvx. Add the following configuration to your MCP client settings to automatically fetch and run the latest version.

{
  "mcpServers": {
    "yfmcp": {
      "command": "uvx",
      "args": ["yfmcp@latest"]
    }
  }
}

To work with options, use these two tools in sequence:

1. yfinance_get_option_dates(symbol): Returns a JSON array of available expiration dates in YYYY-MM-DD format.
2. yfinance_get_option_chain(symbol, expiration_date, option_type): Fetches the actual chain data.

yfinance_get_option_chain Parameters:

• symbol (str): Stock ticker symbol.
• expiration_date (str | null): A specific date from the list returned by get_option_dates. If omitted, fetches all available dates.
• option_type (str, default: 'all'): Which options to return: 'calls', 'puts', or 'all'.

// Step 1: Find dates
const dates = await yfinance_get_option_dates({ symbol: 'AAPL' });

// Step 2: Get calls for the first date
const chain = await yfinance_get_option_chain({
  symbol: 'AAPL',
  expiration_date: dates[0],
  option_type: 'calls'
});

Rate-limit text classifiers may incorrectly identify a ticker as a rate-limit error if the ticker symbol itself contains words associated with rate-limiting. This happens because str(yfinance_exception) includes the ticker symbol in its output.

Fix: When possible, classify errors using the yfinance debug_info or rationale fields instead of parsing the full exception string.

When using tools related to ticker.options or ticker.option_chain(), certain errors must be categorized specifically to avoid misleading the user.

If a timeout, connection-related error, or YFRateLimitError occurs, the error must be reported as NETWORK_ERROR. Do not downgrade these specific errors to NO_DATA or a generic API_ERROR.

If you have cloned the repository and run uv sync, the project includes a .codex/config.toml that registers the local yfmcp server. You can test the server by opening Codex CLI from the repository root and using natural language prompts like:

• Show VOO ticker info
• Show VOO price history for the last 5 days
• Find the ticker symbol for Toyota
• Get AAPL option expiration dates