# Massive MCP

> The `list_dividends` tool fetches full historical cash dividend records for any supported stock ticker. Your AI agent runs this function by accepting parameters like the ticker, date range, and required frequency (annual, quarterly). This gives you a clean dataset of past payouts needed for deep financial modeling and equity research.

## Overview
- **Category:** data-analytics
- **Price:** Free
- **Tags:** dividends, stock-market, financial-data, investing, equity-research

## Description

You're gonna run complex finance queries without ever needing to mess with an API key or a giant spreadsheet. This server hooks your AI client up to the raw historical payout data you need for deep equity research.

The `list_dividends` tool fetches full records of cash dividend payouts for any stock ticker you throw at it. Your agent runs this function, and it gives you a clean, exhaustive dataset of past company distributions needed for serious financial modeling. You're analyzing patterns here; you ain't just checking a number.

When you use `list_dividends`, your AI client retrieves the complete dividend history—every payment counts, whether it was a regular handout or some one-off special distribution. It grabs all cash payouts, so you get the full story on how much money companies are sending back to shareholders over time. You can track every recurring payout and even isolate those supplemental payments that throw off simple calculations.

The tool lets your agent filter results way down, letting you isolate specific payment types or restrict results based on exact dates. Need to see only the special dividends paid out in Q4? Or maybe you want to check payouts strictly from quarterly cycles versus annual ones? You just tell it what you're looking for, and it narrows the focus immediately.

Because the data is so granular, your AI client can track dividend consistency across different frequencies. It helps you see if a company sticks to its payment schedule—whether it's quarterly, or if they only pay once a year. This reveals crucial patterns in corporate commitment that simple charts miss.

It’ll pull together the necessary payout data so your agent calculates key metrics like dividend growth rates and historical yields. You don't need another spreadsheet program to calculate this; the raw data feeds the model, and you get the resulting financial insights back directly. This makes building precise financial models fast.

The server pulls full records of cash payouts for any supported ticker, giving you a massive dataset ready for your analysis. It handles the heavy lifting, gathering every single historical payment record—recurring, special, or supplemental—into one place. The tool allows filtering by ex-dividend date and lets you specify the desired payment frequency to keep your data tight.

When your agent processes this data, it compiles a massive history of payouts, giving you access to thousands of records per ticker. It’s built for serious deep dives into corporate finance, letting you model payout trends over decades without running into data caps or formatting headaches.

The capability to calculate historical yields and track dividend growth rates is what makes this server essential. You get the core payout figures needed to run those calculations yourself, meaning your research remains precise and auditable. It keeps the flow of information moving so you can focus on interpreting the numbers, not cleaning them up.

You'll use this to build sophisticated financial models that track how a company’s payouts have evolved through different economic cycles. You can cross-reference payment types—for instance, comparing consistent quarterly payments against larger, infrequent special distributions—to understand management's true commitment to shareholders. It gathers the full context of cash returns for every ticker it supports.

It processes massive amounts of financial data efficiently. When you set parameters like a specific date range and request payout frequency, the tool delivers only the relevant records. This means your AI client doesn't choke on irrelevant noise; it gets exactly what it needs—the raw, unfiltered historical dividend record for immediate use in your analysis.

## Tools

### list_dividends
Retrieves historical cash dividend payouts for any specified stock ticker.

## Prompt Examples

**Prompt:** 
```
List historical dividends for ticker 'AAPL'.
```

**Response:** 
```
I've retrieved the dividend history for Apple Inc. (AAPL). Recent distributions include a recurring cash dividend of $0.25 with an ex-dividend date of 2024-05-10. Would you like to see the full list of historical payouts?
```

**Prompt:** 
```
Show me special dividends for 'MSFT' sorted by date.
```

**Response:** 
```
Searching for special distributions for Microsoft (MSFT)... I found a notable special dividend record from 2004-11-15 for $3.00. There are no other recent distributions flagged as 'special' in the database.
```

**Prompt:** 
```
Find all dividends for 'KO' with a frequency of 4.
```

**Response:** 
```
Querying quarterly dividends for Coca-Cola (KO)... I've found a consistent history of quarterly distributions (frequency: 4). The most recent was $0.48. Would you like to see the growth trend over the last 5 years?
```

## Capabilities

### Fetch historical payout data
Your agent retrieves the full record of cash dividends for a specific stock ticker.

### Filter by payment type and date
The tool lets you filter results to isolate special, recurring, or supplemental distributions based on dates.

### Analyze dividend frequency trends
You can query for consistency across different frequencies (e.g., quarterly vs. annual) to track payment patterns.

### Calculate historical yields
By providing the necessary payout data, your agent calculates dividend growth rates and historical yields.

## Use Cases

### Calculating total historical yield for a new investment
An analyst is looking at Company X. Instead of downloading five years of annual reports, they prompt their agent: 'Run `list_dividends` for ticker XYZ and calculate the 5-year average dividend yield.' The agent executes the tool, gets all payouts, and returns a single, actionable percentage.

### Checking if a special payout occurred in the past
A portfolio manager asks their agent to check for unique payments. They prompt: 'Use `list_dividends` on ticker ABC and filter specifically for any 'special' distributions after 2015.' The tool returns only those notable, non-recurring payouts.

### Building a dividend tracking bot
A developer needs to feed historical data into a Python trading script. They call `list_dividends` with date range and ticker parameters. The agent sends back structured JSON records, perfect for immediate integration without cleanup.

### Comparing payout frequency across two stocks
You want to compare KO (Coca-Cola) vs. PEP (Pepsi). You ask the agent to run `list_dividends` for both, filtering by 'quarterly'. The system compares the output structure and tells you which company has a more consistent payment schedule.

## Benefits

- **Stop manual data compiling.** You get clean, structured records for thousands of tickers using `list_dividends`. No more cross-referencing multiple financial sites to build a single payout timeline. It just works.
- **Pinpoint specific payment types.** Need to know how much was paid out as a special bonus vs. the regular quarterly dividend? You filter those exact distribution types with `list_dividends` in one query.
- **Model growth rates accurately.** By pulling full historical data, you can feed clean records into your agent and calculate precise dividend growth rates—something messy spreadsheets often mess up.
- **Manage portfolio timing better.** Check the ex-dividend dates for all your holdings instantly. Your agent runs `list_dividends` to help you time sales or purchases against payout cycles.
- **Build reliable trading logic.** Developers integrate this data into bots and research tools using the structured output from `list_dividends`, skipping flaky web scraping entirely.

## How It Works

The bottom line is that you talk to your AI client like a human analyst, and it handles all the data retrieval via Massive.

1. Subscribe to Massive and input your API Key into your AI client.
2. Tell your agent you need a specific type of financial data (e.g., 'Show me the dividend history for AAPL').
3. The agent automatically invokes `list_dividends`, sends the required ticker and date parameters, and returns structured payout records.

## Frequently Asked Questions

**Can I filter dividends by a specific date?**
Yes. You can use the `ex_dividend_date` parameter in the `list_dividends` tool to find distributions occurring on or after a specific YYYY-MM-DD date.

**What types of dividend distributions can I identify?**
The `list_dividends` tool supports filtering by `distribution_type`, including 'recurring', 'special', 'supplemental', 'irregular', and 'unknown'.

**How many dividend records can I retrieve at once?**
By default, the `list_dividends` tool returns 100 results, but you can increase the `limit` parameter up to a maximum of 5000 records per query.

**How do I authenticate when using `list_dividends`?**
You must provide your Massive API key during server setup. Vinkius securely manages this credential, allowing your AI client to access the historical data without exposing raw keys.

**What happens if I run `list_dividends` with an invalid stock ticker?**
The system returns a specific API error message. Your agent will relay this exact code, telling you precisely why the query failed and what input needs correction.

**Does `list_dividends` require parameters other than the stock ticker?**
No, initially providing the ticker is enough to start. You can then refine results in subsequent prompts by specifying frequency or distribution type for deeper analysis.

**What historical depth can I retrieve using `list_dividends`?**
The API provides comprehensive data spanning many years of a ticker's trading life. You can pull decades of payout history, limited only by the company’s record.

**What format is the dividend data delivered in for analysis?**
Data arrives in a structured JSON format. This makes it simple to pipe directly into financial models or Python scripts without requiring complex parsing steps.