# Finance Data MCP � Stocks, Crypto, Forex & Macro Data (`amicable_grid/finance-data-mcp`) Actor
10-tool financial data server for AI agents: stock quotes, financials, analysis, market overview, macro indicators, crypto, forex, SEC filings, earnings, news sentiment. US + India markets. Structured output, intelligent caching, no API keys needed.
- **URL**: https://apify.com/amicable\_grid/finance-data-mcp.md
- **Developed by:** [Satyam Das](https://apify.com/amicable_grid) (community)
- **Categories:** Developer tools
- **Stats:** 2 total users, 1 monthly users, 0.0% runs succeeded, NaN bookmarks
- **User rating**: No ratings yet
## Pricing
Pay per usage
This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have.
Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage
## What's an Apify Actor?
Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".
## How to integrate an Actor?
If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.
In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):
```bash
npm install apify-client
```
In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):
```bash
pip install apify-client
```
In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):
````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash
In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).
If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).
For usage examples, see the [API](#api) section below.
For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).
# README
Finance Data MCP Server
Real-time financial data for AI agents — 10 tools, 2 markets, 0 API keys.
---
### What It Does
A **10-tool financial data server** designed for MCP/AI agent consumption. Get stock quotes, financials, analysis, macro data, crypto prices, forex rates, SEC filings, earnings calendars, and news sentiment — all with structured output and intelligent caching.
Covers **US (NYSE/NASDAQ)** and **India (NSE/BSE)** markets. No API keys needed for core functionality.
---
### Tools Overview
| ## | Tool | What It Returns | PPE Event |
|---|------|----------------|-----------|
| 1 | `stock_quote` | Real-time/delayed prices, volume, change | `financial_data_retrieved` ($0.05) |
| 2 | `stock_financials` | Income statement, balance sheet, cash flow | `financial_data_retrieved` ($0.05) |
| 3 | `stock_analysis` | Analyst recommendations, price targets, key stats | `stock_analysis_completed` ($0.10) |
| 4 | `market_overview` | Major indices, sector performance, market status | `financial_data_retrieved` ($0.05) |
| 5 | `economic_indicators` | GDP, inflation, interest rates, unemployment | `financial_data_retrieved` ($0.05) |
| 6 | `crypto_prices` | BTC, ETH, 15+ altcoins with 24h stats | `financial_data_retrieved` ($0.05) |
| 7 | `currency_rates` | 15+ forex pairs with change tracking | `financial_data_retrieved` ($0.05) |
| 8 | `sec_filings` | Search SEC EDGAR filings by ticker & type | `financial_data_retrieved` ($0.05) |
| 9 | `earnings_calendar` | Upcoming earnings dates, EPS estimates | `financial_data_retrieved` ($0.05) |
| 10 | `news_sentiment` | Financial news with keyword sentiment scoring | `financial_data_retrieved` ($0.05) |
---
### Use Cases
- **AI agent integration** — structured data for Claude, GPT, or any LLM agent via MCP
- **Portfolio monitoring** — check quotes, financials, and analyst ratings
- **Market research** — macro indicators, sector performance, earnings dates
- **India stock analysis** — NSE/BSE data with `.NS` / `.BO` suffix support
- **Crypto & forex** — real-time prices for 15+ coins and currency pairs
- **SEC research** — pull 10-K, 10-Q, 8-K filings for any US company
---
### Input
```json
{
"tool": "stock_quote",
"tickers": ["NVDA", "RELIANCE.NS", "AAPL"]
}
````
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `tool` | string | ✅ | Which financial data tool to invoke |
| `tickers` | string\[] | ✅ | Stock/crypto/forex symbols |
| `financial_type` | string | ❌ | `income_statement`, `balance_sheet`, or `cash_flow` (stock\_financials only) |
| `period` | string | ❌ | `annual` or `quarterly` (default: `annual`) |
| `indicators` | string\[] | ❌ | Which macro indicators (economic\_indicators only) |
| `filing_type` | string | ❌ | `10-K`, `10-Q`, `8-K`, `DEF 14A`, `13-F`, or `ALL` |
| `query` | string | ❌ | Free-text search (sec\_filings, news\_sentiment) |
| `limit` | integer | ❌ | Max results (1–100, default 20) |
***
### Tool Examples
#### Stock Quote
```json
{ "tool": "stock_quote", "tickers": ["NVDA", "RELIANCE.NS", "AAPL"] }
```
#### Stock Financials
```json
{ "tool": "stock_financials", "tickers": ["AAPL"], "financial_type": "income_statement", "period": "annual" }
```
#### Stock Analysis
```json
{ "tool": "stock_analysis", "tickers": ["TCS.NS", "MSFT"], "period": "quarterly" }
```
#### Market Overview
```json
{ "tool": "market_overview" }
```
#### Economic Indicators
```json
{ "tool": "economic_indicators", "indicators": ["GDP", "INFLATION", "INTEREST_RATE", "UNEMPLOYMENT"] }
```
#### Crypto Prices
```json
{ "tool": "crypto_prices", "tickers": ["BTC-USD", "ETH-USD", "SOL-USD"] }
```
#### Currency Rates
```json
{ "tool": "currency_rates", "tickers": ["EURUSD=X", "USDINR=X"] }
```
#### SEC Filings
```json
{ "tool": "sec_filings", "tickers": ["AAPL"], "filing_type": "10-K", "limit": 5 }
```
#### Earnings Calendar
```json
{ "tool": "earnings_calendar", "tickers": ["NVDA", "TSLA"] }
```
#### News Sentiment
```json
{ "tool": "news_sentiment", "tickers": ["AAPL"], "limit": 10 }
```
***
### Output
Each result includes structured data with metadata:
```json
{
"tool": "stock_quote",
"ticker": "NVDA",
"data": {
"current_price": 875.42,
"previous_close": 862.10,
"change_pct": 1.55,
"volume": 45200000,
"market_cap": 2150000000000
},
"source": "yfinance",
"fetched_at": "2026-04-22T10:30:00Z",
"cache_ttl": 60
}
```
***
### India Market Support
| Exchange | Suffix | Example |
|----------|--------|---------|
| NSE India | `.NS` | `RELIANCE.NS`, `TCS.NS`, `INFY.NS` |
| BSE India | `.BO` | `RELIANCE.BO` |
| Crypto | `-USD` | `BTC-USD`, `ETH-USD`, `SOL-USD` |
| Forex | `=X` | `EURUSD=X`, `USDINR=X` |
***
### Data Sources
| Source | Tools | Notes |
|--------|-------|-------|
| Yahoo Finance (yfinance) | Most tools | Free, no API key needed |
| SEC EDGAR | sec\_filings | Free, public data |
| FRED (optional) | economic\_indicators | Set `FRED_API_KEY` env var for live data |
***
### Intelligent Caching
Each tool has a built-in TTL cache:
- Stock quotes: **60 seconds**
- Crypto: **30 seconds**
- Forex: **5 minutes**
- Financials: **1 hour**
- SEC filings: **24 hours**
Repeated requests within the TTL window return cached data instantly — no redundant API calls.
***
### MCP Integration
This actor is designed for **MCP (Model Context Protocol)** consumption. AI agents can call it as a tool with structured input/output, making it ideal for:
- **Claude Code** MCP integrations
- **Cursor IDE** data lookups
- **ChatGPT** custom GPTs
- Any AI agent that needs financial data
***
### Pricing
| Event | Price |
|-------|-------|
| `financial_data_retrieved` | $0.05 per data point |
| `stock_analysis_completed` | $0.10 per analysis (additional, on top of base) |
***
### Architecture
```
src/
├── main.py ## Entry point, tool routing, PPE charging
├── cache.py ## TTL cache layer
├── validators.py ## Input validation
└── tools/
├── stock_quote.py
├── stock_financials.py
├── stock_analysis.py
├── market_overview.py
├── economic_indicators.py
├── crypto_prices.py
├── currency_rates.py
├── sec_filings.py
├── earnings_calendar.py
└── news_sentiment.py
```
***
### Built By
**Satyam Das** — [amicable\_grid on Apify](https://apify.com/amicable_grid)
# Actor input Schema
## `tool` (type: `string`):
Which financial data tool to invoke.
## `tickers` (type: `array`):
Stock/crypto/forex ticker symbols. US: NVDA, AAPL. India NSE: RELIANCE.NS, TCS.NS. Crypto: BTC-USD, ETH-USD. Forex: EURUSD=X.
## `financial_type` (type: `string`):
Which financial statement to retrieve. stock\_financials tool only.
## `period` (type: `string`):
Data period. 'annual' or 'quarterly'. For stock\_financials and stock\_analysis.
## `indicators` (type: `array`):
Which macro indicators. economic\_indicators tool only.
## `filing_type` (type: `string`):
Type of SEC filing to search. sec\_filings tool only.
## `query` (type: `string`):
Free-text search for news\_sentiment and sec\_filings tools.
## `limit` (type: `integer`):
Maximum results to return per request.
## Actor input object example
```json
{
"tool": "stock_quote",
"tickers": [
"NVDA"
],
"financial_type": "income_statement",
"period": "annual",
"indicators": [
"GDP",
"INFLATION",
"INTEREST_RATE",
"UNEMPLOYMENT"
],
"filing_type": "ALL",
"query": "",
"limit": 20
}
```
# API
You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.
## JavaScript example
```javascript
import { ApifyClient } from 'apify-client';
// Initialize the ApifyClient with your Apify API token
// Replace the '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {};
// Run the Actor and wait for it to finish
const run = await client.actor("amicable_grid/finance-data-mcp").call(input);
// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
console.dir(item);
});
// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs
```
## Python example
```python
from apify_client import ApifyClient
# Initialize the ApifyClient with your Apify API token
# Replace '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = {}
# Run the Actor and wait for it to finish
run = client.actor("amicable_grid/finance-data-mcp").call(run_input=run_input)
# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
print(item)
# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start
```
## CLI example
```bash
echo '{}' |
apify call amicable_grid/finance-data-mcp --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=amicable_grid/finance-data-mcp",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "Finance Data MCP � Stocks, Crypto, Forex & Macro Data",
"description": "10-tool financial data server for AI agents: stock quotes, financials, analysis, market overview, macro indicators, crypto, forex, SEC filings, earnings, news sentiment. US + India markets. Structured output, intelligent caching, no API keys needed.",
"version": "0.1",
"x-build-id": "kgRVYis9DtQRDurfE"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/amicable_grid~finance-data-mcp/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-amicable_grid-finance-data-mcp",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/acts/amicable_grid~finance-data-mcp/runs": {
"post": {
"operationId": "runs-sync-amicable_grid-finance-data-mcp",
"x-openai-isConsequential": false,
"summary": "Executes an Actor and returns information about the initiated run in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/runsResponseSchema"
}
}
}
}
}
}
},
"/acts/amicable_grid~finance-data-mcp/run-sync": {
"post": {
"operationId": "run-sync-amicable_grid-finance-data-mcp",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"components": {
"schemas": {
"inputSchema": {
"type": "object",
"required": [
"tool"
],
"properties": {
"tool": {
"title": "Tool",
"enum": [
"stock_quote",
"stock_financials",
"stock_analysis",
"market_overview",
"economic_indicators",
"crypto_prices",
"currency_rates",
"sec_filings",
"earnings_calendar",
"news_sentiment"
],
"type": "string",
"description": "Which financial data tool to invoke.",
"default": "stock_quote"
},
"tickers": {
"title": "Tickers",
"type": "array",
"description": "Stock/crypto/forex ticker symbols. US: NVDA, AAPL. India NSE: RELIANCE.NS, TCS.NS. Crypto: BTC-USD, ETH-USD. Forex: EURUSD=X.",
"items": {
"type": "string"
},
"default": [
"NVDA"
]
},
"financial_type": {
"title": "Financial Statement Type",
"enum": [
"income_statement",
"balance_sheet",
"cash_flow"
],
"type": "string",
"description": "Which financial statement to retrieve. stock_financials tool only.",
"default": "income_statement"
},
"period": {
"title": "Period",
"enum": [
"annual",
"quarterly"
],
"type": "string",
"description": "Data period. 'annual' or 'quarterly'. For stock_financials and stock_analysis.",
"default": "annual"
},
"indicators": {
"title": "Economic Indicators",
"type": "array",
"description": "Which macro indicators. economic_indicators tool only.",
"items": {
"type": "string"
},
"default": [
"GDP",
"INFLATION",
"INTEREST_RATE",
"UNEMPLOYMENT"
]
},
"filing_type": {
"title": "SEC Filing Type",
"enum": [
"10-K",
"10-Q",
"8-K",
"DEF 14A",
"13-F",
"ALL"
],
"type": "string",
"description": "Type of SEC filing to search. sec_filings tool only.",
"default": "ALL"
},
"query": {
"title": "Search Query",
"type": "string",
"description": "Free-text search for news_sentiment and sec_filings tools.",
"default": ""
},
"limit": {
"title": "Result Limit",
"minimum": 1,
"maximum": 100,
"type": "integer",
"description": "Maximum results to return per request.",
"default": 20
}
}
},
"runsResponseSchema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"actId": {
"type": "string"
},
"userId": {
"type": "string"
},
"startedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"finishedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"status": {
"type": "string",
"example": "READY"
},
"meta": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"example": "API"
},
"userAgent": {
"type": "string"
}
}
},
"stats": {
"type": "object",
"properties": {
"inputBodyLen": {
"type": "integer",
"example": 2000
},
"rebootCount": {
"type": "integer",
"example": 0
},
"restartCount": {
"type": "integer",
"example": 0
},
"resurrectCount": {
"type": "integer",
"example": 0
},
"computeUnits": {
"type": "integer",
"example": 0
}
}
},
"options": {
"type": "object",
"properties": {
"build": {
"type": "string",
"example": "latest"
},
"timeoutSecs": {
"type": "integer",
"example": 300
},
"memoryMbytes": {
"type": "integer",
"example": 1024
},
"diskMbytes": {
"type": "integer",
"example": 2048
}
}
},
"buildId": {
"type": "string"
},
"defaultKeyValueStoreId": {
"type": "string"
},
"defaultDatasetId": {
"type": "string"
},
"defaultRequestQueueId": {
"type": "string"
},
"buildNumber": {
"type": "string",
"example": "1.0.0"
},
"containerUrl": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "integer",
"example": 1
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
},
"usageTotalUsd": {
"type": "number",
"example": 0.00005
},
"usageUsd": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "number",
"example": 0.00005
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
}
}
}
}
}
}
}
}
```