octagon-financials-mcp

Octagon Financials MCP

The Octagon Financials MCP server provides specialized AI-powered financial statement analysis capabilities by integrating with advanced financial analysis agents. Covers over 8,000 public companies with comprehensive analysis of income statements, balance sheets, cash flow statements, financial ratios, and analysts' estimates. Add unlimited financial statement analysis functionality to any MCP client including Claude Desktop, Cursor, and other popular MCP-enabled applications.

Powered by Octagon AI - Learn more about the Financials Agent at docs.octagonagents.com

🚀 Core Differentiators

✅ Comprehensive Coverage - Over 8,000 public companies with financial data
✅ Historical Analysis - Historical data dating back to 2018 enables robust time-series analysis
✅ Real-Time Updates - Continuous daily updates for real-time insights
✅ Universal MCP Integration - Add financial statement analysis to any MCP client
✅ Multi-Domain Analysis - Income statements, balance sheets, cash flows, and financial ratios
✅ Advanced Financial Metrics - Revenue growth, margins, ratios, operational efficiency analysis

Get Your Octagon API Key

To use Octagon Financials MCP, you need to:

1. Sign up for a free account at Octagon
2. After logging in, from left menu, navigate to API Keys
3. Generate a new API key
4. Use this API key in your configuration as the OCTAGON_API_KEY value

Prerequisites

Before installing or running Octagon Financials MCP, you need to have npx (which comes with Node.js and npm) installed on your system.

Mac (macOS)

1. Install Homebrew (if you don't have it):

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   

2. Install Node.js (includes npm and npx):

   brew install node
   

   This will install the latest version of Node.js, npm, and npx.

3. Verify installation:

   node -v
   npm -v
   npx -v
   

Windows

1. Download the Node.js installer:
   • Go to https://nodejs.org/ and download the LTS version for Windows.
2. Run the installer and follow the prompts. This will install Node.js, npm, and npx.
3. Verify installation: Open Command Prompt and run:

   node -v
   npm -v
   npx -v
   

If you see version numbers for all three, you are ready to proceed with the installation steps below.

Installation

Running on Claude Desktop

To configure Octagon Financials MCP for Claude Desktop:

1. Open Claude Desktop
2. Go to Settings > Developer > Edit Config
3. Add the following to your claude_desktop_config.json (Replace your-octagon-api-key with your Octagon API key):

{
  "mcpServers": {
    "octagon-financials-mcp": {
      "command": "npx",
      "args": ["-y", "octagon-financials-mcp@latest"],
      "env": {
        "OCTAGON_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

4. Restart Claude for the changes to take effect

Running on Cursor

Configuring Cursor Desktop 🖥️ Note: Requires Cursor version 0.45.6+

To configure Octagon Financials MCP in Cursor:

1. Open Cursor Settings
2. Go to Features > MCP Servers
3. Click "+ Add New MCP Server"
4. Enter the following:
   • Name: "octagon-financials-mcp" (or your preferred name)
   • Type: "command"
   • Command: env OCTAGON_API_KEY=your-octagon-api-key npx -y octagon-financials-mcp

If you are using Windows and are running into issues, try cmd /c "set OCTAGON_API_KEY=your-octagon-api-key && npx -y octagon-financials-mcp"

Replace your-octagon-api-key with your Octagon API key.

After adding, refresh the MCP server list to see the new tools. The Composer Agent will automatically use Octagon Financials MCP when appropriate, but you can explicitly request it by describing your financial analysis needs. Access the Composer via Command+L (Mac), select "Agent" next to the submit button, and enter your query.

Running on Windsurf

Add this to your ./codeium/windsurf/model_config.json:

{
  "mcpServers": {
    "octagon-financials-mcp": {
      "command": "npx",
      "args": ["-y", "octagon-financials-mcp@latest"],
      "env": {
        "OCTAGON_API_KEY": "YOUR_API_KEY_HERE"
      }
    }
  }
}

Running with npx

env OCTAGON_API_KEY=your_octagon_api_key npx -y octagon-financials-mcp

Manual Installation

npm install -g octagon-financials-mcp

Octagon Financials Agent

Model Name: octagon-financials-agent

Specialized agent for public companies' financial statement analysis and ratio calculations.

Capabilities

• Analyze public companies' financial statement
• Calculate financial metrics and ratios
• Compare performance indicators across companies
• Evaluate profitability, liquidity, and efficiency metrics
• Track financial performance over time
• Conduct peer comparisons and benchmarking

Use Cases

The Financials Agent is best for:

• Deep financial analysis of public companies
• Comparison of company financial performance
• Ratio analysis and financial health assessment
• Trend analysis of key financial metrics
• Competitive positioning analysis

Example Queries

Get Income Statement Growth

Fetch year-over-year growth rates for key income statement metrics of a given company.

@octagon-financials-agent Retrieve year-over-year growth in key income-statement items for AAPL, limited to 5 records and filtered by period FY.

Get Balance Sheet Statement Growth

Obtain annual growth rates for essential balance sheet items of a specific company.

@octagon-financials-agent Retrieve year-over-year growth in key balance-sheet items for AAPL, limited to 5 records and filtered by period FY.

Get Cash Flow Statement Growth

Access annual cash-flow growth metrics of a specific company.

@octagon-financials-agent Retrieve cash-flow growth metrics for AAPL, limited to 5 records and filtered by period FY.

Get Financial Growth

Retrieve year-over-year growth data across major financial metrics for a given company.

@octagon-financials-agent Retrieve year-over-year growth in key financial metrics for AAPL, limited to 5 records and filtered by period FY.

Get Income Statement

Fetch real-time income statement data for a given company.

@octagon-financials-agent Retrieve real-time income statement data for AAPL, limited to 5 records and filtered by period FY.

Get Balance Sheet Statement

Retrieve detailed balance sheet statement data for a specific company.

@octagon-financials-agent Retrieve detailed balance sheet statement data for AAPL, limited to 5 records and filtered by period FY.

Get Cash Flow Statement

Obtain real-time or historical cash flow statement data for a specific company.

@octagon-financials-agent Retrieve real-time or historical cash flow statement data for AAPL, limited to 5 records and filtered by period FY.

Get Revenue Product Segmentation

Access detailed annual revenue data segmented by product categories for a given company.

@octagon-financials-agent Retrieve detailed revenue by product segment for AAPL, using the annual period and flat response structure.

Get Revenue Product Segmentation

Fetch annual revenue breakdown by specific product segments for a given company.

@octagon-financials-agent Retrieve detailed revenue by product segment for AAPL, for the annual period with a flat response structure.

Get Revenue Geographic Segmentation

Retrieve detailed annual revenue data segmented geographically for a specific company.

@octagon-financials-agent Retrieve detailed revenue by geographic segment for AAPL, for the annual period with a flat response structure.

Get Analyst Estimates

Obtain analyst financial forecasts for a given company.

@octagon-financials-agent Retrieve analyst financial estimates for AAPL for the annual period, limited to 10 records on page 0.

How to Create Effective Prompts for Financial Data Analysis

When working with financial data, consider these strategies for more effective prompts:

1. Specify time periods: Include exact fiscal periods or calendar dates.

   • Example: "Extract quarterly revenue growth rates for AAPL from Q1 2021 through Q4 2023."

2. Request comparative analysis: Ask for comparisons across companies or time periods.

   • Example: "Compare gross margins for MSFT, GOOGL, and AMZN over the last 8 quarters."

3. Focus on specific metrics: Clearly identify which financial metrics you need.

   • Example: "Calculate the debt-to-equity ratio trend for TSLA from 2020 to present."

4. Combine metrics for deeper insights: Request calculations that combine multiple data points.

   • Example: "Analyze the relationship between R&D spending and revenue growth for semiconductor companies."

5. Specify visualization needs: Indicate if you need data presented visually.

   • Example: "Create a chart showing NVDA's quarterly EPS versus analyst estimates for the past 3 years."

6. Request trend analysis: Ask for identification of patterns over time.

   • Example: "Identify trends in operating margins for FB over the past 5 years and highlight significant changes."

7. Incorporate industry benchmarks: Ask for comparisons against industry standards.

   • Example: "How does AMD's P/E ratio compare to the semiconductor industry average?"

8. Target specific financial events: Focus on data around earnings releases or other events.

   • Example: "Extract revenue surprises for NFLX during the last 6 earnings reports."

Financial Data Fields

Income Statement Data

Balance Sheet Data

Cash Flow Statement Data

Financial Ratios

Earnings & Estimates

Company Financial Metrics

Growth & Profitability Metrics

Segment & Geographic Data

Dividend & Capital Return Data

Industry & Peer Comparison

Note: Some fields may require premium access or might not be available for all securities.

Features

✅ Comprehensive Financial Analysis

• Income statement analysis
• Balance sheet analysis
• Cash flow statement analysis
• Financial ratio calculations
• Growth rate analysis
• Performance indicators assessment

✅ Universal Company Coverage

• Over 8,000 public companies
• All major financial metrics
• Real-time data updates
• Historical data back to 2018
• Cross-company comparisons
• Time-series analysis

✅ Advanced Analysis Tools

• Financial ratio calculations
• Trend analysis and forecasting
• Segment performance analysis
• Operational efficiency metrics
• Analysts' estimates integration

Available Tool

octagon-financials-agent

Comprehensive financial statement analysis across over 8,000 public companies.

The tool uses a single prompt parameter that accepts a natural language query. Include all relevant details in your prompt for optimal results.

Documentation

For comprehensive documentation on using Financial Statements capabilities, please visit our official documentation at: https://docs.octagonagents.com

Specifically for the Financials Agent: Financials Agent Guide

The documentation includes:

• Detailed API references
• Financial analysis methodology guidelines
• Examples and use cases
• Best practices for financial statement analysis
• Advanced features and capabilities

Troubleshooting

1. API Key Issues: Ensure your Octagon API key is correctly set in the environment or config file.
2. Connection Issues: Make sure the connectivity to the Octagon API is working properly.
3. Rate Limiting: No rate limits apply to Financials MCP - execute unlimited queries.

License

MIT

⭐ Star this repo if you find it helpful for your financial statement analysis needs!