An MCP server that securely interfaces with your iMessage database via the Model Context Protocol (MCP), allowing LLMs to query and analyze iMessage conversations. It includes robust phone number validation, attachment processing, contact management, group chat handling, and full support for sending and receiving messages.
# investor-agent: A Financial Analysis MCP Server
## Overview
The **investor-agent** is a Model Context Protocol (MCP) server that provides comprehensive financial insights and analysis to Large Language Models. It leverages real-time market data, news, and advanced analytics to help users obtain:
- Detailed ticker reports including company overview, news, key metrics, performance, dates, analyst recommendations, and upgrades/downgrades.
- Options data highlighting high open interest.
- Historical price trends for stocks.
- Essential financial statements (income, balance sheet, cash flow) formatted in millions USD.
- Up-to-date institutional ownership and mutual fund holdings.
- Earnings history and insider trading activity.
The server integrates with [yfinance](https://pypi.org/project/yfinance/) for market data retrieval and [BraveSearch](https://pypi.org/project/brave-search-python-client/) for search capabilities.
## Prerequisites
- **Python:** 3.12 or higher
- **Package Manager:** [uv](https://docs.astral.sh/uv/)
## Installation
First, install **uv** if you haven't already:
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
Then, you can run the **investor-agent** MCP server using `uvx`:
```bash
uvx investor-agent
```
## Tools
The **investor-agent** server comes with several tools to support financial analysis:
### Ticker Information
1. **`get_ticker_data`**
- **Description:** Retrieves a comprehensive report for a given ticker symbol, including company overview, news, key metrics, performance, dates, analyst recommendations, and upgrades/downgrades.
- **Input:**
- `ticker` (string): Stock ticker symbol (e.g., `"AAPL"`).
- **Return:** A formatted multi-section report.
2. **`get_available_options`**
- **Description:** Provides a list of stock options with the highest open interest.
- **Inputs:**
- `ticker_symbol` (string): Stock ticker symbol.
- `num_options` (int, optional): Number of options to return (default: 10).
- `start_date` & `end_date` (string, optional): Date range in `YYYY-MM-DD` format.
- `strike_lower` & `strike_upper` (float, optional): Desired strike price range.
- `option_type` (string, optional): Option type (`"C"` for calls, `"P"` for puts).
- **Return:** A formatted table of options data.
3. **`get_price_history`**
- **Description:** Retrieves historical price data for a specific ticker.
- **Inputs:**
- `ticker` (string): Stock ticker symbol.
- `period` (string): Time period (choose from `"1d"`, `"5d"`, `"1mo"`, `"3mo"`, `"6mo"`, `"1y"`, `"2y"`, `"5y"`, `"10y"`, `"ytd"`, `"max"`).
- **Return:** A table showing price history.
### Financial Data Tools
1. **`get_financial_statements`**
- **Description:** Fetches financial statements (income, balance, or cash flow) formatted in millions USD.
- **Inputs:**
- `ticker` (string): Stock ticker symbol.
- `statement_type` (string): `"income"`, `"balance"`, or `"cash"`.
- `frequency` (string): `"quarterly"` or `"annual"`.
- **Return:** A formatted financial statement.
2. **`get_institutional_holders`**
- **Description:** Retrieves details about major institutional and mutual fund holders.
- **Input:**
- `ticker` (string): Stock ticker symbol.
- **Return:** Two formatted tables listing institutional and mutual fund holders.
3. **`get_earnings_history`**
- **Description:** Retrieves a formatted table of earnings history.
- **Input:**
- `ticker` (string): Stock ticker symbol.
- **Return:** A table displaying historical earnings data.
4. **`get_insider_trades`**
- **Description:** Fetches the recent insider trading activity for a given ticker.
- **Input:**
- `ticker` (string): Stock ticker symbol.
- **Return:** A formatted table showing insider trades.
## Usage with MCP Clients
To integrate **investor-agent** with an MCP client (for example, Claude Desktop), add the following configuration to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"investor": {
"command": "path/to/uvx/command/uvx",
"args": ["investor-agent"],
"env": {
"BRAVE_SEARCH_API_KEY": "your_brave_search_api_key_here"
}
}
}
}
```
## Debugging
You can leverage the MCP inspector to debug the server:
```bash
npx @modelcontextprotocol/inspector uvx investor-agent
```
For log monitoring, check the following directories:
- macOS: `~/Library/Logs/Claude/mcp*.log`
- Windows: `%APPDATA%\Claude\logs\mcp*.log`
## Development
For local development and testing:
1. Use the MCP inspector as described in the [Debugging](#debugging) section.
2. Test using Claude Desktop with this configuration:
```json
{
"mcpServers": {
"investor": {
"command": "path/to/uv/command/uv",
"args": ["--directory", "path/to/investor-agent", "run", "investor-agent"],
}
}
}
```
## License
This MCP server is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.
