Metadata-Version: 2.4
Name: stocksense
Version: 0.1.1
Summary: StockSense — MCP server providing AI agents with access to financial data: SEC filings, price history, financials, insider trades
License-Expression: MIT
Project-URL: Homepage, https://github.com/mikejj-creation/stocksense
Project-URL: Repository, https://github.com/mikejj-creation/stocksense
Project-URL: Issues, https://github.com/mikejj-creation/stocksense/issues
Keywords: mcp,finance,sec,edgar,stocks,ai,llm,stocksense
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: yfinance>=0.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Dynamic: license-file

# StockSense

mcp-name: io.github.mikejj-creation/stocksense

[![PyPI version](https://img.shields.io/pypi/v/stocksense)](https://pypi.org/project/stocksense/)
[![PyPI downloads](https://img.shields.io/pypi/dm/stocksense)](https://pypi.org/project/stocksense/)
[![Python versions](https://img.shields.io/pypi/pyversions/stocksense)](https://pypi.org/project/stocksense/)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

An MCP (Model Context Protocol) server that gives AI agents access to financial data — SEC EDGAR filings, market fundamentals, insider trades, and price history.

## Installation

```bash
pip install -e .
```

For development:

```bash
pip install -e ".[dev]"
```

## Usage

### Run the server

```bash
# Either:
stocksense

# Or:
python -m stocksense
```

### Claude Desktop configuration

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "stocksense": {
      "command": "stocksense"
    }
  }
}
```

### Available Tools

| Tool | Description |
|------|-------------|
| `price_history` | Get historical OHLCV price data for any ticker |
| `quote` | Get current price, market cap, P/E, 52-week range |
| `search_filings` | Search SEC EDGAR filings (10-K, 10-Q, 8-K) |
| `get_filing` | Get full text of a specific SEC filing |
| `insider_trades` | Get recent insider buys/sells from Form 4 filings |
| `financials` | Get income statement, balance sheet, cash flow, and key ratios |
| `analyze_company` | Comprehensive research brief aggregating all data sources |
| `compare_companies` | Compare key metrics across multiple companies side-by-side |
| `earnings` | Quarterly earnings history with EPS estimates vs actuals |
| `company_profile` | Company profile: sector, industry, and business description |
| `dividends` | Dividend history and current yield |
| `key_events` | Upcoming earnings dates, ex-dividend date, and estimates |
| `technicals` | Technical indicators: SMA, EMA, RSI, MACD, and performance |

### Example queries

- "What's AAPL's price history for the last month?"
- "Get me a quote for MSFT"
- "Show me TSLA's weekly prices over the past year"
- "Show me Apple's recent 10-K filings"
- "What insider trades happened at Tesla recently?"
- "Show me Apple's financial statements"
- "Give me a research brief on Tesla"
- "Compare AAPL, MSFT, and GOOGL"
- "Show me Apple's earnings history"
- "What sector is NVIDIA in?"
- "Show me AAPL's dividend history"
- "When is Microsoft's next earnings date?"
- "What are Tesla's technical indicators?"

## Data Sources

- **yfinance** — price data, quotes, financial statements, analyst consensus
- **SEC EDGAR** — free, unlimited filings and insider trades (no API key needed)

## Development

```bash
# Run tests
pytest

# Run linter
ruff check src/ tests/
```

## License

MIT
