API Documentation

Client Libraries

Introduction

MCPFinancials provides a JSON-RPC interface for accessing financial data, metrics, and analysis tools. This API is designed to be easily integrated with large language models (LLMs) and other applications that need reliable financial data context.

Our API follows the JSON-RPC 2.0 specification, providing a simple and consistent interface for all methods. The base URL for all API requests is:

https://mcpfinancials.com/api/jsonrpc

Authentication

MCPFinancials API offers two access levels:

Public Access

Public access to the API is available without authentication, but with limited rate limits and feature restrictions. Use the following endpoint for public access:

https://mcpfinancials.com/api/jsonrpc

API Key Authentication

For higher rate limits and access to premium features, use API key authentication. API keys can be obtained by registering for a paid account.

To use API key authentication, include your API key in the request headers: 

{
  "Content-Type": "application/json",
  "X-API-Key": "your_api_key_here"
}

Authenticated requests should be sent to the secure endpoint:

https://mcpfinancials.com/api/jsonrpc/secure

JSON-RPC Interface

All API requests follow the JSON-RPC 2.0 specification. Requests must be sent as POST requests with a JSON body in the following format:

{ "jsonrpc": "2.0", "method": "method.name", "params": { "param1": "value1", "param2": "value2" }, "id": 1 }

Responses will also follow the JSON-RPC 2.0 specification:

{ "jsonrpc": "2.0", "result": { "key1": "value1", "key2": "value2" }, "id": 1 }

If an error occurs, the response will include an error object:

{ "jsonrpc": "2.0", "error": { "code": -32602, "message": "Invalid params: required parameter missing" }, "id": 1 }

Financial Metrics

MCPFinancials provides a comprehensive set of financial metrics and ratios for analysis. Use these methods to discover and calculate financial metrics:

Get Available Metrics

Returns a list of all available financial metrics and their schemas.

discover.getAvailableMetrics

View details →

Get Metric Schema

Returns the schema for a specific financial metric.

discover.getMetricSchema

View details →

Calculate Ratio

Calculate a financial ratio using provided values.

finance.calculateRatio

View details →

Calculate Metric

Calculate any financial metric by ID using provided values.

finance.calculateMetric

View details →

discover.getAvailableMetrics

Get a list of all available financial metrics and their basic information.

Parameters:

category (optional)

Filter metrics by category (e.g., "profitability", "liquidity")

creator_id (optional)

Filter metrics by creator ID

is_custom (optional)

Filter metrics by whether they are custom or standard

Example Request:

{ "jsonrpc": "2.0", "method": "discover.getAvailableMetrics", "params": { "category": "valuation" }, "id": 1 }

Example Response:

{ "jsonrpc": "2.0", "result": { "metrics": [ { "id": "price_to_earnings", "name": "Price-to-Earnings Ratio", "description": "Ratio of share price to earnings per share", "category": "valuation" }, { "id": "price_to_book", "name": "Price-to-Book Ratio", "description": "Ratio of share price to book value per share", "category": "valuation" }, // Additional metrics... ] }, "id": 1 }

SEC EDGAR Data

MCPFinancials provides access to SEC EDGAR filings and data through the following methods:

Get Company Filings

Retrieve a list of filings for a specific company.

edgar.getCompanyFilings

View details →

Get Filing Content

Retrieve the content of a specific SEC filing.

edgar.getFilingContent

View details →

Search Filings

Search for specific information across SEC filings.

edgar.searchFilings

View details →

Get Financial Data

Extract structured financial data from SEC filings.

edgar.getFinancialData

View details →

Market Data

Access historical and current stock market data through the following methods:

Get EOD Data

Retrieve end-of-day stock price data.

marketstack.getEODData

View details →

Get Historical Data

Retrieve historical stock price data for a date range.

marketstack.getHistoricalData

View details →

Technical Indicators

Calculate technical indicators for financial analysis:

Calculate RSI

Calculate Relative Strength Index for a series of prices.

technicals.rsi

View details →

Calculate MACD

Calculate Moving Average Convergence Divergence.

technicals.macd

View details →

Calculate Bollinger Bands

Calculate Bollinger Bands for a series of prices.

technicals.bollinger

View details →

Calculate Stochastic Oscillator

Calculate Stochastic Oscillator for a series of prices.

technicals.stochastic

View details →

Rate Limits

The MCPFinancials API enforces rate limits to ensure fair usage. Rate limits vary by authentication method:

Authentication Rate Limit Period
Public (no API key) 50 requests per hour
Basic plan 500 requests per hour
Pro plan 5,000 requests per hour

If you exceed your rate limit, the API will return a 429 Too Many Requests error. You can check your current rate limit usage in the response headers:

  • X-RateLimit-Limit: Maximum number of requests allowed in the current period
  • X-RateLimit-Remaining: Number of requests remaining in the current period
  • X-RateLimit-Reset: Time (in seconds) until the rate limit resets

Error Handling

The MCPFinancials API uses standard JSON-RPC error codes. Here are some common error codes you may encounter:

Code Message Description
-32700 Parse error Invalid JSON was received by the server
-32600 Invalid request The JSON sent is not a valid Request object
-32601 Method not found The method does not exist / is not available
-32602 Invalid params Invalid method parameter(s)
-32603 Internal error Internal JSON-RPC error
-32000 to -32099 Server error Reserved for implementation-defined server errors
-32001 Rate limit exceeded You have exceeded your rate limit

Python Client

Use our Python client library to easily integrate MCPFinancials into your Python applications:

# Installation pip install mcpfinancials
# Basic usage from mcpfinancials import MCPClient # Initialize the client client = MCPClient(api_key="your_api_key_here") # API key is optional # Get available metrics metrics = client.discover.get_available_metrics(category="valuation") print(metrics) # Calculate a financial metric result = client.finance.calculate_metric( metric_id="price_to_earnings", values={ "price": 150.25, "earnings_per_share": 5.30 } ) print(result)

JavaScript Client

Use our JavaScript client library to easily integrate MCPFinancials into your web applications:

// Installation npm install mcpfinancials
// Basic usage import { MCPClient } from 'mcpfinancials'; // Initialize the client const client = new MCPClient({ apiKey: 'your_api_key_here' }); // API key is optional // Get available metrics client.discover.getAvailableMetrics({ category: 'valuation' }) .then(metrics => { console.log(metrics); }) .catch(error => { console.error(error); }); // Calculate a financial metric client.finance.calculateMetric({ metric_id: 'price_to_earnings', values: { price: 150.25, earnings_per_share: 5.30 } }) .then(result => { console.log(result); }) .catch(error => { console.error(error); });