Insider Transactions

Overview

FinMCP provides three distinct tools for tracking insider activity. Understanding the differences between them is crucial for effective insider trading analysis.

yf_ticker_insider_purchases

Returns purchase-only insider transactions, filtering out sales and other transaction types. This tool is ideal for identifying bullish insider sentiment.

Parameters

ticker

string

required

Ticker symbol (e.g., “AAPL”, “MSFT”)

response_format

enum

default:"json"

Output format: json or markdown

preview_limit

integer

default:25

Number of rows to preview in markdown format (max 200)

save

object

Save results to file

Show properties

format

enum

required

File format: csv or json

filename

string

Custom filename (auto-generated if omitted)

Returns

A DataFrame containing insider purchase details:

Shares: Number of shares purchased
Value: Dollar value of the purchase
URL: Link to SEC filing
Text: Description of the transaction

Example Usage

const result = await use_mcp_tool({
  server_name: "finmcp",
  tool_name: "yf_ticker_insider_purchases",
  arguments: {
    ticker: "META",
    response_format: "json"
  }
});

yf_ticker_insider_transactions

Returns all insider transactions, including purchases, sales, option exercises, and other transaction types. Use this for comprehensive insider activity analysis.

Parameters

ticker

string

required

Ticker symbol (e.g., “AAPL”, “MSFT”)

response_format

enum

default:"json"

Output format: json or markdown

preview_limit

integer

default:25

Number of rows to preview in markdown format (max 200)

save

object

Save results to file

Show properties

format

enum

required

File format: csv or json

filename

string

Custom filename (auto-generated if omitted)

Returns

A DataFrame containing all insider transaction details:

Insider: Name of the insider
Position: Title/role at the company
Date: Transaction date
Shares: Number of shares transacted
Value: Dollar value of the transaction
Transaction: Type (Purchase, Sale, Option Exercise, etc.)
URL: Link to SEC filing

Example Usage

const result = await use_mcp_tool({
  server_name: "finmcp",
  tool_name: "yf_ticker_insider_transactions",
  arguments: {
    ticker: "GOOGL",
    response_format: "markdown",
    preview_limit: 20
  }
});

Example Response

{
  "data": {
    "__type__": "dataframe",
    "columns": ["Insider", "Position", "Date", "Shares", "Value", "Transaction", "URL"],
    "index": [0, 1, 2],
    "data": [
      ["Jane Smith", "Chief Financial Officer", "2024-01-15", 10000, 1500000, "Sale", "https://www.sec.gov/..."],
      ["John Doe", "Director", "2024-01-10", 5000, 750000, "Purchase", "https://www.sec.gov/..."],
      ["Bob Johnson", "Chief Technology Officer", "2024-01-05", 25000, 3750000, "Option Exercise", "https://www.sec.gov/..."]
    ]
  }
}

yf_ticker_insider_roster_holders

Returns current insider positions (point-in-time snapshot), showing how many shares each insider currently holds. Unlike transaction data, this shows the cumulative position.

Parameters

ticker

string

required

Ticker symbol (e.g., “AAPL”, “MSFT”)

response_format

enum

default:"json"

Output format: json or markdown

preview_limit

integer

default:25

Number of rows to preview in markdown format (max 200)

save

object

Save results to file

Show properties

format

enum

required

File format: csv or json

filename

string

Custom filename (auto-generated if omitted)

Returns

A DataFrame containing current insider holdings:

Name: Insider name
Position: Title/role at the company
Date: Most recent report date
Shares: Total shares currently held
Value: Current market value of holdings
% Out: Percentage of outstanding shares

Example Usage

const result = await use_mcp_tool({
  server_name: "finmcp",
  tool_name: "yf_ticker_insider_roster_holders",
  arguments: {
    ticker: "AMZN",
    response_format: "json"
  }
});

Example Response

{
  "data": {
    "__type__": "dataframe",
    "columns": ["Name", "Position", "Date", "Shares", "Value", "% Out"],
    "index": [0, 1, 2],
    "data": [
      ["Jeffrey P. Bezos", "Executive Chairman", "2024-12-31", 987654321, 150000000000, 0.0950],
      ["Andrew R. Jassy", "President and CEO", "2024-12-31", 12345678, 1875000000, 0.0012],
      ["Brian T. Olsavsky", "Senior Vice President and CFO", "2024-12-31", 5432109, 825000000, 0.0005]
    ]
  }
}

Key Differences

Insider Purchases

What: Purchase transactions onlyWhen: Looking for bullish signalsShows: Individual buy transactions

Insider Transactions

What: All transaction typesWhen: Comprehensive activity trackingShows: Buys, sales, exercises, grants

Insider Roster

What: Current total holdingsWhen: Assessing current ownershipShows: Point-in-time positions

When to Use Each Tool

Use yf_ticker_insider_purchases when:

Screening for stocks with recent insider buying
Looking for bullish insider sentiment signals
You only care about purchases, not sales
Building buy-side insider alerts

Use yf_ticker_insider_transactions when:

You need a complete picture of insider activity
Analyzing both bullish and bearish signals
Tracking executive compensation events
Performing comprehensive insider trading analysis

Use yf_ticker_insider_roster_holders when:

Assessing current insider ownership concentration
Comparing insider holdings across companies
Understanding management skin in the game
You need total positions, not individual trades

These tools complement ownership analysis by providing shares outstanding data.

yf_ticker_shares

Returns the most recent shares outstanding data.

Parameters

ticker

string

required

Ticker symbol (e.g., “AAPL”, “MSFT”)

response_format

enum

default:"json"

Output format: json or markdown

preview_limit

integer

default:25

Number of rows to preview in markdown format (max 200)

save

object

Save results to file

Returns

Shares outstanding time series (recent data).

yf_ticker_shares_full

Returns the complete historical shares outstanding data with optional date filtering.

Parameters

ticker

string

required

Ticker symbol (e.g., “AAPL”, “MSFT”)

start

string

Start date in YYYY-MM-DD format (e.g., “2020-01-01”)

end

string

End date in YYYY-MM-DD format (e.g., “2024-12-31”)

response_format

enum

default:"json"

Output format: json or markdown

preview_limit

integer

default:25

Number of rows to preview in markdown format (max 200)

save

object

Save results to file

Returns

Complete historical shares outstanding time series.

Example Usage

const result = await use_mcp_tool({
  server_name: "finmcp",
  tool_name: "yf_ticker_shares_full",
  arguments: {
    ticker: "AAPL",
    start: "2020-01-01",
    end: "2024-12-31",
    response_format: "json"
  }
});

Use Cases

Track share dilution or buyback programs over time
Calculate historical market capitalization
Analyze the impact of stock-based compensation
Normalize ownership percentages across different time periods

yf_ticker_major_holders - High-level ownership breakdown
yf_ticker_institutional_holders - Institutional ownership details
yf_ticker_info - Company info including shares outstanding

Overview

Market Data

Company Information

Financial Statements

Corporate Actions

Analyst Data

Ownership & Holdings

Options

Screening & Discovery

Markets & Sectors

Reference

​Overview

​yf_ticker_insider_purchases

​Parameters

​Returns

​Example Usage

​yf_ticker_insider_transactions

​Parameters

​Returns

​Example Usage

​Example Response

​yf_ticker_insider_roster_holders

​Parameters

​Returns

​Example Usage

​Example Response

​Key Differences

Insider Purchases

Insider Transactions

Insider Roster

​When to Use Each Tool

​Share Data Tools

​yf_ticker_shares

​Parameters

​Returns

​yf_ticker_shares_full

​Parameters

​Returns

​Example Usage

​Use Cases

​Related Tools

Build docs developers (and LLMs) love

Overview

yf_ticker_insider_purchases

Parameters

Returns

Example Usage

yf_ticker_insider_transactions

Parameters

Returns

Example Usage

Example Response

yf_ticker_insider_roster_holders

Parameters

Returns

Example Usage

Example Response

Key Differences

When to Use Each Tool

Share Data Tools

yf_ticker_shares

Parameters

Returns

yf_ticker_shares_full

Parameters

Returns

Example Usage

Use Cases

Related Tools