Metadata-Version: 2.4
Name: gurufocus-mcp
Version: 0.5.1
Summary: Unofficial MCP server for GuruFocus financial data
Project-URL: Homepage, https://github.com/u-daveblack/gurufocus-mcp
Project-URL: Documentation, https://github.com/u-daveblack/gurufocus-mcp#readme
Project-URL: Repository, https://github.com/u-daveblack/gurufocus-mcp
Author: David Black
License-Expression: MIT
Keywords: ai,finance,gurufocus,llm,mcp,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: fastmcp>=0.4
Requires-Dist: gurufocus-api
Requires-Dist: python-toon>=0.1
Requires-Dist: structlog>=24.0
Provides-Extra: dev
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# Unofficial GuruFocus MCP Server

An MCP (Model Context Protocol) server that exposes GuruFocus financial data to AI assistants like Claude. Built with FastMCP for seamless integration with Claude Desktop and other MCP clients.

## Features

- **50+ Analysis Tools**: Stocks, gurus, insiders, politicians, economic data, and more
- **Data Resources**: Direct access to formatted financial data via URI templates
- **Multiple Transports**: stdio (Claude Desktop), HTTP/SSE, WebSocket
- **Error Handling**: Graceful handling of invalid symbols, rate limits, and API errors
- **TOON Format**: 30-60% token reduction vs JSON for efficient LLM contexts

## Requirements

- Python 3.11+
- GuruFocus API token ([Get one here](https://www.gurufocus.com/api.php))

## Installation

```bash
pip install gurufocus-mcp
```

Or with uv:

```bash
uv add gurufocus-mcp
```

## Quick Start

### 1. Set your API token

```bash
export GURUFOCUS_API_TOKEN=your-token-here
```

### 2. Run the server

```bash
# Default stdio transport (for Claude Desktop)
gurufocus-mcp

# HTTP transport for web clients
gurufocus-mcp --transport http --port 8000
```

## Claude Desktop Integration

Add to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "gurufocus": {
      "command": "gurufocus-mcp",
      "env": {
        "GURUFOCUS_API_TOKEN": "your-token-here"
      }
    }
  }
}
```

If using uv or a virtual environment:

```json
{
  "mcpServers": {
    "gurufocus": {
      "command": "uv",
      "args": ["run", "gurufocus-mcp"],
      "env": {
        "GURUFOCUS_API_TOKEN": "your-token-here"
      }
    }
  }
}
```

After adding the configuration, restart Claude Desktop. You should see the GuruFocus tools available in Claude's interface.

## Available Tools

### Stock Tools (21 tools)

| Tool                          | Description                                                      |
| ----------------------------- | ---------------------------------------------------------------- |
| `get_stock_summary`           | Comprehensive overview: price, valuation, GF Score               |
| `get_stock_financials`        | Financial statements (income, balance sheet, cash flow)          |
| `get_stock_keyratios`         | Key financial ratios (profitability, liquidity, growth)          |
| `get_stock_quote`             | Real-time stock quote with OHLCV data                            |
| `get_stock_price_history`     | Historical price data                                            |
| `get_stock_price_ohlc`        | Historical OHLC price bars for technical analysis                |
| `get_stock_volume`            | Historical trading volume data                                   |
| `get_stock_unadjusted_price`  | Historical unadjusted (pre-split) prices                         |
| `get_stock_dividends`         | Dividend history                                                 |
| `get_stock_current_dividend`  | Current dividend yield and payment info                          |
| `get_stock_analyst_estimates` | Analyst earnings/revenue estimates                               |
| `get_stock_insider_trades`    | Insider trading activity for a stock                             |
| `get_stock_gurus`             | Guru holdings in a specific stock                                |
| `get_stock_executives`        | Company executives and directors                                 |
| `get_stock_trades_history`    | Guru trades history for a stock                                  |
| `get_stock_operating_data`    | Operating metrics and KPIs                                       |
| `get_stock_segments_data`     | Business and geographic segment breakdown                        |
| `get_stock_ownership`         | Ownership breakdown (institutional, insider, float)              |
| `get_stock_indicator_history` | Historical ownership indicators                                  |
| `get_stock_indicators`        | List of 240+ available stock indicators                          |
| `get_stock_indicator`         | Time series data for a specific indicator                        |

### Insider Tools (7 tools)

| Tool                      | Description                              |
| ------------------------- | ---------------------------------------- |
| `get_insider_updates`     | Recent insider transaction updates       |
| `get_insider_ceo_buys`    | CEO buy transactions (bullish signal)    |
| `get_insider_cfo_buys`    | CFO buy transactions                     |
| `get_insider_cluster_buys`| Cluster buy signals (multiple insiders)  |
| `get_insider_double_buys` | Double-down buy signals                  |
| `get_insider_triple_buys` | Triple-down buy signals                  |
| `get_insider_list`        | Browse known insiders                    |

### Guru Tools (4 tools)

| Tool                    | Description                               |
| ----------------------- | ----------------------------------------- |
| `get_gurulist`          | List all tracked super investors          |
| `get_guru_picks`        | Guru's stock picks and trading activity   |
| `get_guru_aggregated`   | Guru's complete portfolio with holdings   |
| `get_guru_realtime_picks`| Recent trading activity across all gurus |

### Politician Tools (2 tools)

| Tool                         | Description                            |
| ---------------------------- | -------------------------------------- |
| `get_politicians`            | List tracked politicians               |
| `get_politician_transactions`| Politician stock transactions          |

### Reference Data Tools (6 tools)

| Tool                  | Description                               |
| --------------------- | ----------------------------------------- |
| `get_exchange_list`   | List worldwide stock exchanges            |
| `get_exchange_stocks` | Stocks listed on a specific exchange      |
| `get_index_list`      | List worldwide market indexes             |
| `get_index_stocks`    | Constituent stocks in a market index      |
| `get_country_currency`| Country currency mapping                  |
| `get_funda_updated`   | Recently updated fundamentals             |

### Economic Data Tools (3 tools)

| Tool                     | Description                            |
| ------------------------ | -------------------------------------- |
| `get_economic_indicators`| List available economic indicators     |
| `get_economic_indicator` | Time series for economic indicator     |
| `get_financial_calendar` | Financial calendar (earnings, IPOs)    |

### Personal/Account Tools (6 tools)

| Tool                   | Description                               |
| ---------------------- | ----------------------------------------- |
| `get_api_usage`        | API usage statistics                      |
| `get_user_screeners`   | User's saved screeners                    |
| `get_screener_results` | Run a saved screener                      |
| `get_portfolios`       | User's portfolios                         |
| `get_portfolio_detail` | Portfolio holdings and performance        |
| `get_portfolio_changes`| Portfolio changes over time               |

### ETF Tools (2 tools)

| Tool                  | Description                               |
| --------------------- | ----------------------------------------- |
| `get_etf_list`        | List available ETFs                       |
| `get_etf_sector_weighting` | ETF sector allocation               |

### Analysis Tools (2 tools)

| Tool                  | Description                               |
| --------------------- | ----------------------------------------- |
| `compare_stocks`      | Compare multiple stocks side-by-side      |
| `get_stock_news`      | Recent news for a stock                   |

## Available Resources

Resources provide direct data access via URI templates:

### Stock Resources

```
gurufocus://stock/{symbol}/summary      - Company overview
gurufocus://stock/{symbol}/gf-score     - GF Score details
gurufocus://stock/{symbol}/valuation    - Valuation metrics
gurufocus://stock/{symbol}/financials   - Financial statements
gurufocus://stock/{symbol}/ratios       - Key financial ratios
gurufocus://stock/{symbol}/dividends    - Dividend information
gurufocus://stock/{symbol}/insiders     - Insider trading
gurufocus://stock/{symbol}/estimates    - Analyst estimates
```

### Guru Resources

```
gurufocus://gurus                       - List of tracked gurus
gurufocus://guru/{guru_id}/picks        - Guru's portfolio
gurufocus://guru/{guru_id}/trades       - Guru's recent trades
gurufocus://stock/{symbol}/gurus        - Gurus holding a stock
```

## Example Conversations

### Basic Stock Analysis

```
User: What's the GF Score for Apple?

Claude: [Uses get_gf_score tool]
Apple (AAPL) has a GF Score of 92/100, indicating high quality:
- Financial Strength: 8/10
- Profitability Rank: 10/10
- Growth Rank: 7/10
- Value Rank: 5/10
- Momentum Rank: 8/10
```

### Stock Comparison

```
User: Compare MSFT, GOOGL, and META on valuation metrics

Claude: [Uses compare_stocks tool]
Here's a side-by-side comparison...
```

### Finding Value Opportunities

```
User: Find undervalued tech stocks with high quality scores

Claude: [Uses find_undervalued tool with sector filter]
I found 15 technology stocks trading below their GF Value...
```

### Investment Research

```
User: Create an investment thesis for NVDA

Claude: [Uses investment_thesis prompt + multiple tools]
## Investment Thesis: NVIDIA Corporation

### 1. Company Overview
[Detailed analysis using get_stock_summary]

### 2. Financial Health
[Analysis using get_financials, get_key_ratios]
...
```

## Configuration Options

### Environment Variables

| Variable              | Description              | Default                                  |
| --------------------- | ------------------------ | ---------------------------------------- |
| `GURUFOCUS_API_TOKEN` | Your GuruFocus API token | Required                                 |
| `GURUFOCUS_BASE_URL`  | API base URL             | `https://api.gurufocus.com/public/user/` |
| `MCP_SERVER_NAME`     | Server name for MCP      | `gurufocus-mcp`                          |

### Command Line Options

```bash
gurufocus-mcp [OPTIONS]

Options:
  --transport [stdio|http|sse]  Transport protocol (default: stdio)
  --port PORT                   HTTP server port (default: 8000)
  --host HOST                   HTTP server host (default: 127.0.0.1)
  --help                        Show help message
```

## Error Handling

The server provides helpful error messages for common issues:

### Invalid Symbol
```json
{
  "error": true,
  "error_type": "invalid_symbol",
  "message": "The symbol 'INVALID' was not found or is invalid.",
  "suggestions": [
    "Check that the symbol is spelled correctly",
    "Verify the stock is listed on a supported exchange"
  ]
}
```

### Rate Limiting
```json
{
  "error": true,
  "error_type": "rate_limit",
  "message": "API rate limit exceeded. Try again in 60 seconds.",
  "details": {"retry_after": 60}
}
```

### Authentication
```json
{
  "error": true,
  "error_type": "authentication_error",
  "message": "API authentication failed. Please check your GuruFocus API token."
}
```

## Development

### Running Tests

```bash
# Run all tests
uv run pytest packages/gurufocus-mcp/tests/ -v

# Run specific test file
uv run pytest packages/gurufocus-mcp/tests/test_integration.py -v
```

### Project Structure

```
gurufocus_mcp/
├── __init__.py          # Package exports
├── config.py            # Configuration management
├── server.py            # MCP server setup
├── formatting.py        # TOON/JSON formatters
├── tools/               # Tool handlers (50+ tools)
│   ├── stocks.py        # Stock data tools
│   ├── insiders.py      # Insider activity tools
│   ├── gurus.py         # Guru/institutional investor tools
│   ├── politicians.py   # Politician trading tools
│   ├── economic.py      # Economic data tools
│   ├── reference.py     # Reference data tools
│   ├── personal.py      # Account/portfolio tools
│   └── etfs.py          # ETF tools
└── resources/           # Resource handlers
```

## Related Packages

- **gurufocus-api**: Python client library for GuruFocus API
- **fastmcp**: MCP server framework

## Disclaimer

This project is an unofficial tool and is not affiliated with, endorsed by, or sponsored by **GuruFocus.com, LLC** or any of its subsidiaries.

- **Non-Affiliation**: This software is developed independently and does not represent the views or opinions of GuruFocus.
- **Trademarks**: "GuruFocus" and the GuruFocus logo are trademarks of GuruFocus.com, LLC.
- **Data Usage**: Users are responsible for ensuring their use of this tool complies with the GuruFocus [Terms of Use](https://www.gurufocus.com/term-of-use) and any applicable API usage agreements. This tool is provided "as is" and intended for educational and personal use.
- **No Warranty**: The authors of this software make no warranty as to the accuracy, completeness, or reliability of the data retrieved using this tool.
- **No Investment Advice**: The information provided by this tool is for informational and educational purposes only and does not constitute investment advice, financial advice, trading advice, or any other sort of advice. You should not treat any of the tool's content as such.
- **External Methodologies**: References to third-party investment strategies, books, authors, or personalities (e.g., Phil Town, Rule #1, Warren Buffett) are for educational purposes to demonstrate the application of published methodologies. This project is not affiliated with, endorsed by, or sponsored by any referenced individuals or entities. All trademarks belong to their respective owners.

## License

MIT

## Support

- [GuruFocus API Documentation](https://www.gurufocus.com/api.php)
- [MCP Protocol Specification](https://modelcontextprotocol.io/)
- [Report Issues](https://github.com/your-org/gurufocus-mcp/issues)
