Skip to content
Back to search

alpha-vantage-mcp

MCP Server for Alpha Advantage API

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/berlinbra--alpha-vantage-mcp/badge.svg)](/listings/berlinbra--alpha-vantage-mcp)

HTML

<a href="/listings/berlinbra--alpha-vantage-mcp"><img src="/api/listings/berlinbra--alpha-vantage-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Using Claude Desktop

Installing via Docker

- Clone the repository and build a local image to be utilized by your Claude desktop client

cd alpha-vantage-mcp
docker build -t mcp/alpha-vantage .

- Change your `claude_desktop_config.json` to match the following, replacing `REPLACE_API_KEY` with your actual key:

> `claude_desktop_config.json` path > > - On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json` > - On Windows: `%APPDATA%/Claude/claude_desktop_config.json`

{
  "mcpServers": {
    "alphavantage": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "-e",
        "ALPHA_VANTAGE_API_KEY",
        "mcp/alpha-vantage"
      ],
      "env": {
        "ALPHA_VANTAGE_API_KEY": "REPLACE_API_KEY"
      }
    }
  }
}

Installing via Smithery

To install Alpha Vantage MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@berlinbra/alpha-vantage-mcp):

npx -y @smithery/cli install @berlinbra/alpha-vantage-mcp --client claude

<summary> <h3> Development/Unpublished Servers Configuration <h3> </summary>

<details>

{
 "mcpServers": {
  "alpha-vantage-mcp": {
   "args": [
    "--directory",
    "/Users/{INSERT_USER}/YOUR/PATH/TO/alpha-vantage-mcp",
    "run",
    "alpha-vantage-mcp"
   ],
   "command": "uv",
   "env": {
    "ALPHA_VANTAGE_API_KEY": "<insert api key>"
   }
  }
 }
}

</details>

Install packages

uv install -e .

Running

After connecting Claude client with the MCP tool via json file and installing the packages, Claude should see the server's mcp tools:

You can run the sever yourself via: In alpha-vantage-mcp repo:

uv run src/alpha_vantage_mcp/server.py

with inspector

* npx @modelcontextprotocol/inspector uv --directory /Users/{INSERT_USER}/YOUR/PATH/TO/alpha-vantage-mcp run src/alpha_vantage_mcp/server.py `

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 823 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Alpha Vantage MCP Server
  2. [![smithery badge](https://smithery.ai/badge/@berlinbra/alpha-vantage-mcp)](https://smithery.ai/server/@berlinbra/alpha-vantage-mcp)
  3. A Model Context Protocol (MCP) server that provides real-time access to financial market data through the free [Alpha Vantage API](https://www.alphavantage.co/documentation/). This server implements a standardized interface for retrieving stock quotes and company information.
  4. <a href="https://glama.ai/mcp/servers/0wues5td08"><img width="380" height="200" src="https://glama.ai/mcp/servers/0wues5td08/badge" alt="AlphaVantage-MCP MCP server" /></a>
  5. # Features
  6. - Real-time stock quotes with price, volume, and change data
  7. - Detailed company information including sector, industry, and market cap
  8. - Real-time cryptocurrency exchange rates with bid/ask prices
  9. - Daily, weekly, and monthly cryptocurrency time series data
  10. - Real-time options chain data with Greeks and implied volatility
  11. - Historical options chain data with advanced filtering and sorting
  12. - Comprehensive ETF profile data with holdings, sector allocation, and key metrics
  13. - Upcoming earnings calendar with customizable time horizons
  14. - Historical earnings data with annual and quarterly reports
  15. - Built-in error handling and rate limit management
  16. ## Installation
  17. ### Using Claude Desktop
  18. #### Installing via Docker
  19. - Clone the repository and build a local image to be utilized by your Claude desktop client
  20. ```sh
  21. cd alpha-vantage-mcp
  22. docker build -t mcp/alpha-vantage .
  23. ```
  24. - Change your `claude_desktop_config.json` to match the following, replacing `REPLACE_API_KEY` with your actual key:
  25. > `claude_desktop_config.json` path
  26. >
  27. > - On MacOS: `~/Library/Application\ Support/Claude/claude_desktop_config.json`
  28. > - On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
  29. ```json
  30. {
  31. "mcpServers": {
  32. "alphavantage": {
  33. "command": "docker",
  34. "args": [
  35. "run",
  36. "-i",
  37. "-e",
  38. "ALPHA_VANTAGE_API_KEY",
  39. "mcp/alpha-vantage"
  40. ],
  41. "env": {
  42. "ALPHA_VANTAGE_API_KEY": "REPLACE_API_KEY"
  43. }
  44. }
  45. }
  46. }
  47. ```
  48. #### Installing via Smithery
  49. To install Alpha Vantage MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@berlinbra/alpha-vantage-mcp):
  50. ```bash
  51. npx -y @smithery/cli install @berlinbra/alpha-vantage-mcp --client claude
  52. ```
  53. <summary> <h3> Development/Unpublished Servers Configuration <h3> </summary>
  54. <details>
  55. ```json
  56. {
  57. "mcpServers": {
  58. "alpha-vantage-mcp": {
  59. "args": [
  60. "--directory",
  61. "/Users/{INSERT_USER}/YOUR/PATH/TO/alpha-vantage-mcp",
  62. "run",
  63. "alpha-vantage-mcp"
  64. ],
  65. "command": "uv",
  66. "env": {
  67. "ALPHA_VANTAGE_API_KEY": "<insert api key>"
  68. }
  69. }
  70. }
  71. }
  72. ```
  73. </details>
  74. #### Install packages
  75. ```
  76. uv install -e .
  77. ```
  78. #### Running
  79. After connecting Claude client with the MCP tool via json file and installing the packages, Claude should see the server's mcp tools:
  80. You can run the sever yourself via:
  81. In alpha-vantage-mcp repo:
  82. ```
  83. uv run src/alpha_vantage_mcp/server.py
  84. ```
  85. with inspector
  86. ```
  87. * npx @modelcontextprotocol/inspector uv --directory /Users/{INSERT_USER}/YOUR/PATH/TO/alpha-vantage-mcp run src/alpha_vantage_mcp/server.py `
  88. ```
  89. ## Available Tools
  90. The server implements twelve tools:
  91. - `get-stock-quote`: Get the latest stock quote for a specific company
  92. - `get-company-info`: Get stock-related information for a specific company
  93. - `get-crypto-exchange-rate`: Get current cryptocurrency exchange rates
  94. - `get-time-series`: Get historical daily price data for a stock
  95. - `get-realtime-options`: Get real-time options chain data with Greeks and implied volatility
  96. - `get-historical-options`: Get historical options chain data with advanced filtering and sorting capabilities
  97. - `get-etf-profile`: Get comprehensive ETF profile information including holdings and sector allocation
  98. - `get-crypto-daily`: Get daily time series data for a cryptocurrency
  99. - `get-crypto-weekly`: Get weekly time series data for a cryptocurrency
  100. - `get-crypto-monthly`: Get monthly time series data for a cryptocurrency
  101. - `get-earnings-calendar`: Get upcoming earnings calendar data for companies
  102. - `get-historical-earnings`: Get historical earnings data for a specific company
  103. ### get-stock-quote
  104. **Input Schema:**
  105. ```json
  106. {
  107. "symbol": {
  108. "type": "string",
  109. "description": "Stock symbol (e.g., AAPL, MSFT)"
  110. }
  111. }
  112. ```
  113. **Example Response:**
  114. ```
  115. Stock quote for AAPL:
  116. Price: $198.50
  117. Change: $2.50 (+1.25%)
  118. Volume: 58942301
  119. High: $199.62
  120. Low: $197.20
  121. ```
  122. ### get-company-info
  123. Retrieves detailed company information for a given symbol.
  124. **Input Schema:**
  125. ```json
  126. {
  127. "symbol": {
  128. "type": "string",
  129. "description": "Stock symbol (e.g., AAPL, MSFT)"
  130. }
  131. }
  132. ```
  133. **Example Response:**
  134. ```
  135. Company information for AAPL:
  136. Name: Apple Inc
  137. Sector: Technology
  138. Industry: Consumer Electronics
  139. Market Cap: $3000000000000
  140. Description: Apple Inc. designs, manufactures, and markets smartphones...
  141. Exchange: NASDAQ
  142. Currency: USD
  143. ```
  144. ### get-crypto-exchange-rate
  145. Retrieves real-time cryptocurrency exchange rates with additional market data.
  146. **Input Schema:**
  147. ```json
  148. {
  149. "crypto_symbol": {
  150. "type": "string",
  151. "description": "Cryptocurrency symbol (e.g., BTC, ETH)"
  152. },
  153. "market": {
  154. "type": "string",
  155. "description": "Market currency (e.g., USD, EUR)",
  156. "default": "USD"
  157. }
  158. }
  159. ```
  160. **Example Response:**
  161. ```
  162. Cryptocurrency exchange rate for BTC/USD:
  163. From: Bitcoin (BTC)
  164. To: United States Dollar (USD)
  165. Exchange Rate: 43521.45000
  166. Last Updated: 2024-12-17 19:45:00 UTC
  167. Bid Price: 43521.00000
  168. Ask Price: 43522.00000
  169. ```
  170. ### get-time-series
  171. Retrieves daily time series (OHLCV) data with optional date filtering.
  172. **Input Schema:**
  173. ```json
  174. {
  175. "symbol": {
  176. "type": "string",
  177. "description": "Stock symbol (e.g., AAPL, MSFT)"
  178. },
  179. "outputsize": {
  180. "type": "string",
  181. "description": "compact (latest 100 data points) or full (up to 20 years of data). When start_date or end_date is specified, defaults to 'full'",
  182. "default": "compact"
  183. },
  184. "start_date": {
  185. "type": "string",
  186. "description": "Optional: Start date in YYYY-MM-DD format for filtering results",
  187. "pattern": "^20[0-9]{2}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$"
  188. },
  189. "end_date": {
  190. "type": "string",
  191. "description": "Optional: End date in YYYY-MM-DD format for filtering results",
  192. "pattern": "^20[0-9]{2}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$"
  193. },
  194. "limit": {
  195. "type": "integer",
  196. "description": "Optional: Number of data points to return when no date filtering is applied (default: 5)",
  197. "default": 5,
  198. "minimum": 1
  199. }
  200. }
  201. ```
  202. **Example Response (Recent Data):**
  203. ```
  204. Time Series Data for AAPL (Last Refreshed: 2024-12-17 16:00:00):
  205. (Showing 5 most recent data points)
  206. Date: 2024-12-16
  207. Open: $195.09
  208. High: $197.68
  209. Low: $194.83
  210. Close: $197.57
  211. Volume: 55,751,011
  212. ---
  213. Date: 2024-12-13
  214. Open: $194.50
  215. High: $196.25
  216. Low: $193.80
  217. Close: $195.12
  218. Volume: 48,320,567
  219. ---
  220. ```
  221. **Example Response (Date Range Filtering):**
  222. ```
  223. Time Series Data for AAPL (Last Refreshed: 2024-12-17 16:00:00):
  224. Date Range: 2024-12-01 to 2024-12-07 (5 data points)
  225. Date: 2024-12-06
  226. Open: $191.25
  227. High: $193.80
  228. Low: $190.55
  229. Close: $192.90
  230. Volume: 52,145,890
  231. ---
  232. Date: 2024-12-05
  233. Open: $189.75
  234. High: $192.40
  235. Low: $188.90
  236. Close: $191.30
  237. Volume: 47,892,345
  238. ---
  239. ```
  240. ### get-realtime-options
  241. Retrieves real-time options chain data for a stock with optional Greeks calculation and contract filtering.
  242. **⚠️ PREMIUM SUBSCRIPTION REQUIRED**: This endpoint requires Alpha Vantage Premium with either the 600 requests/minute or 1200 requests/minute plan. The standard 75 requests/minute plan and free accounts will receive placeholder/demo data instead of real market data. For most use cases, consider using `get-historical-options` which works with all API key tiers.
  243. **Input Schema:**
  244. ```json
  245. {
  246. "symbol": {
  247. "type": "string",
  248. "description": "Stock symbol (e.g., AAPL, MSFT)"
  249. },
  250. "require_greeks": {
  251. "type": "boolean",
  252. "description": "Optional: Enable Greeks and implied volatility calculation (default: false)",
  253. "default": false
  254. },
  255. "contract": {
  256. "type": "string",
  257. "description": "Optional: Specific options contract ID to retrieve"
  258. },
  259. "datatype": {
  260. "type": "string",
  261. "description": "Optional: Response format (json or csv, default: json)",
  262. "enum": ["json", "csv"],
  263. "default": "json"
  264. }
  265. }
  266. ```
  267. **Example Response:**
  268. ```
  269. Realtime Options Data for AAPL
  270. Last Updated: 2025-01-21 16:00:00
  271. === Expiration: 2025-01-24 ===
  272. Strike: $220.0 (CALL)
  273. Last: $5.25
  274. Bid: $5.10
  275. Ask: $5.30
  276. Volume: 1250
  277. Open Interest: 8420
  278. IV: 0.28
  279. Delta: 0.65
  280. Gamma: 0.02
  281. Theta: -0.15
  282. Vega: 0.45
  283. Rho: 0.12
  284. ---
  285. Strike: $220.0 (PUT)
  286. Last: $1.85
  287. Bid: $1.80
  288. Ask: $1.90
  289. Volume: 820
  290. Open Interest: 5240
  291. IV: 0.25
  292. Delta: -0.35
  293. Gamma: 0.02
  294. Theta: -0.12
  295. Vega: 0.42
  296. Rho: -0.08
  297. ---
  298. ```
  299. **Note**: The above example shows real market data which is only available with Alpha Vantage Premium 600+ requests/minute plans. Users with free accounts or 75 requests/minute plans will see placeholder data (symbols like "XXYYZZ", dates like "2099-99-99") and should use `get-historical-options` instead.
  300. ### get-historical-options
  301. Retrieves historical options chain data with advanced filtering and sorting capabilities to find specific contracts.
  302. **Input Schema:**
  303. ```json
  304. {
  305. "symbol": {
  306. "type": "string",
  307. "description": "Stock symbol (e.g., AAPL, MSFT)"
  308. },
  309. "date": {
  310. "type": "string",
  311. "description": "Optional: Trading date in YYYY-MM-DD format (defaults to previous trading day, must be after 2008-01-01)",
  312. "pattern": "^20[0-9]{2}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$"
  313. },
  314. "expiry_date": {
  315. "type": "string",
  316. "description": "Optional: Filter by expiration date in YYYY-MM-DD format",
  317. "pattern": "^20[0-9]{2}-(?:0[1-9]|1[0-2])-(?:0[1-9]|[12][0-9]|3[01])$"
  318. },
  319. "min_strike": {
  320. "type": "number",
  321. "description": "Optional: Minimum strike price filter (e.g., 100.00)",
  322. "minimum": 0
  323. },
  324. "max_strike": {
  325. "type": "number",
  326. "description": "Optional: Maximum strike price filter (e.g., 200.00)",
  327. "minimum": 0
  328. },
  329. "contract_id": {
  330. "type": "string",
  331. "description": "Optional: Filter by specific contract ID (e.g., MSTR260116C00000500)"
  332. },
  333. "contract_type": {
  334. "type": "string",
  335. "description": "Optional: Filter by contract type (call or put)",
  336. "enum": ["call", "put", "C", "P"]
  337. },
  338. "limit": {
  339. "type": "integer",
  340. "description": "Optional: Number of contracts to return after filtering (default: 10, use -1 for all contracts)",
  341. "default": 10,
  342. "minimum": -1
  343. },
  344. "sort_by": {
  345. "type": "string",
  346. "description": "Optional: Field to sort by",
  347. "enum": ["strike", "expiration", "volume", "open_interest", "implied_volatility", "delta", "gamma", "theta", "vega", "rho", "last", "bid", "ask"],
  348. "default": "strike"
  349. },
  350. "sort_order": {
  351. "type": "string",
  352. "description": "Optional: Sort order",
  353. "enum": ["asc", "desc"],
  354. "default": "asc"
  355. }
  356. }
  357. ```
  358. **Example Response (Basic):**
  359. ```
  360. Historical Options Data for AAPL (2024-02-20):
  361. Status: success
  362. Found 156 contracts, sorted by: strike (asc)
  363. Contract Details:
  364. Contract ID: AAPL240315C00190000
  365. Expiration: 2024-03-15
  366. Strike: $190.00
  367. Type: call
  368. Last: $8.45
  369. Bid: $8.40
  370. Ask: $8.50
  371. Volume: 1245
  372. Open Interest: 4567
  373. Implied Volatility: 0.25
  374. Greeks:
  375. Delta: 0.65
  376. Gamma: 0.04
  377. Theta: -0.15
  378. Vega: 0.30
  379. Rho: 0.25
  380. ---
  381. ```
  382. **Example Response (Filtered):**
  383. ```
  384. Historical Options Data for MSTR (2024-02-20):
  385. Status: success
  386. Filters: Expiry: 2026-01-16, Strike: min $400 - max $600, Type: call
  387. Found 3 contracts, sorted by: strike (asc)
  388. Contract Details:
  389. Contract ID: MSTR260116C00000500
  390. Expiration: 2026-01-16
  391. Strike: $500.00
  392. Type: call
  393. Last: $125.30
  394. Bid: $124.50
  395. Ask: $126.10
  396. Volume: 89
  397. Open Interest: 1234
  398. ---
  399. ```
  400. ### get-etf-profile
  401. Retrieves comprehensive ETF profile information including basic metrics, sector allocation, and top holdings.
  402. **Input Schema:**
  403. ```json
  404. {
  405. "symbol": {
  406. "type": "string",
  407. "description": "ETF symbol (e.g., QQQ, SPY, VTI)"
  408. }
  409. }
  410. ```
  411. **Example Response:**
  412. ```
  413. ETF profile for QQQ:
  414. ETF Profile
  415. Basic Information:
  416. Net Assets: $352,700,000,000
  417. Net Expense Ratio: 0.200%
  418. Portfolio Turnover: 8.0%
  419. Dividend Yield: 0.50%
  420. Inception Date: 1999-03-10
  421. Leveraged: NO
  422. Sector Allocation:
  423. INFORMATION TECHNOLOGY: 51.9%
  424. COMMUNICATION SERVICES: 15.4%
  425. CONSUMER DISCRETIONARY: 12.2%
  426. CONSUMER STAPLES: 4.8%
  427. HEALTHCARE: 4.5%
  428. INDUSTRIALS: 4.4%
  429. UTILITIES: 1.4%
  430. MATERIALS: 1.3%
  431. ENERGY: 0.5%
  432. FINANCIALS: 0.4%
  433. Top Holdings:
  434. 1. NVDA - NVIDIA CORP: 9.80%
  435. 2. MSFT - MICROSOFT CORP: 8.85%
  436. 3. AAPL - APPLE INC: 7.35%
  437. 4. AMZN - AMAZON.COM INC: 5.65%
  438. 5. AVGO - BROADCOM INC: 5.14%
  439. 6. META - META PLATFORMS INC CLASS A: 3.63%
  440. 7. NFLX - NETFLIX INC: 3.10%
  441. 8. TSLA - TESLA INC: 2.66%
  442. 9. GOOGL - ALPHABET INC CLASS A: 2.49%
  443. 10. COST - COSTCO WHOLESALE CORP: 2.49%
  444. ... and 92 more holdings
  445. Total Holdings: 102
  446. ```
  447. ### get-crypto-daily
  448. Retrieves daily time series data for a cryptocurrency.
  449. **Input Schema:**
  450. ```json
  451. {
  452. "symbol": {
  453. "type": "string",
  454. "description": "Cryptocurrency symbol (e.g., BTC, ETH)"
  455. },
  456. "market": {
  457. "type": "string",
  458. "description": "Market currency (e.g., USD, EUR)",
  459. "default": "USD"
  460. }
  461. }
  462. ```
  463. **Example Response:**
  464. ```
  465. Daily cryptocurrency time series for SOL in USD:
  466. Daily Time Series for Solana (SOL)
  467. Market: United States Dollar (USD)
  468. Last Refreshed: 2025-04-17 00:00:00 UTC
  469. Date: 2025-04-17
  470. Open: 131.31000000 USD
  471. High: 131.67000000 USD
  472. Low: 130.74000000 USD
  473. Close: 131.15000000 USD
  474. Volume: 39652.22195178
  475. ---
  476. Date: 2025-04-16
  477. Open: 126.10000000 USD
  478. High: 133.91000000 USD
  479. Low: 123.46000000 USD
  480. Close: 131.32000000 USD
  481. Volume: 1764240.04195810
  482. ---
  483. ```
  484. ### get-crypto-weekly
  485. Retrieves weekly time series data for a cryptocurrency.
  486. **Input Schema:**
  487. ```json
  488. {
  489. "symbol": {
  490. "type": "string",
  491. "description": "Cryptocurrency symbol (e.g., BTC, ETH)"
  492. },
  493. "market": {
  494. "type": "string",
  495. "description": "Market currency (e.g., USD, EUR)",
  496. "default": "USD"
  497. }
  498. }
  499. ```
  500. **Example Response:**
  501. ```
  502. Weekly cryptocurrency time series for SOL in USD:
  503. Weekly Time Series for Solana (SOL)
  504. Market: United States Dollar (USD)
  505. Last Refreshed: 2025-04-17 00:00:00 UTC
  506. Date: 2025-04-17
  507. Open: 128.32000000 USD
  508. High: 136.00000000 USD
  509. Low: 123.46000000 USD
  510. Close: 131.15000000 USD
  511. Volume: 4823091.05667581
  512. ---
  513. Date: 2025-04-13
  514. Open: 105.81000000 USD
  515. High: 134.11000000 USD
  516. Low: 95.16000000 USD
  517. Close: 128.32000000 USD
  518. Volume: 18015328.38860037
  519. ---
  520. ```
  521. ### get-crypto-monthly
  522. Retrieves monthly time series data for a cryptocurrency.
  523. **Input Schema:**
  524. ```json
  525. {
  526. "symbol": {
  527. "type": "string",
  528. "description": "Cryptocurrency symbol (e.g., BTC, ETH)"
  529. },
  530. "market": {
  531. "type": "string",
  532. "description": "Market currency (e.g., USD, EUR)",
  533. "default": "USD"
  534. }
  535. }
  536. ```
  537. **Example Response:**
  538. ```
  539. Monthly cryptocurrency time series for SOL in USD:
  540. Monthly Time Series for Solana (SOL)
  541. Market: United States Dollar (USD)
  542. Last Refreshed: 2025-04-17 00:00:00 UTC
  543. Date: 2025-04-17
  544. Open: 124.51000000 USD
  545. High: 136.18000000 USD
  546. Low: 95.16000000 USD
  547. Close: 131.15000000 USD
  548. Volume: 34268628.85976021
  549. ---
  550. Date: 2025-03-31
  551. Open: 148.09000000 USD
  552. High: 180.00000000 USD
  553. Low: 112.00000000 USD
  554. Close: 124.54000000 USD
  555. Volume: 42360395.75443056
  556. ---
  557. ```
  558. ### get-earnings-calendar
  559. Retrieves upcoming earnings calendar data for companies with customizable time horizons and sorting capabilities.
  560. **Input Schema:**
  561. ```json
  562. {
  563. "symbol": {
  564. "type": "string",
  565. "description": "Optional: Stock symbol to filter earnings for a specific company (e.g., AAPL, MSFT, IBM)"
  566. },
  567. "horizon": {
  568. "type": "string",
  569. "description": "Optional: Time horizon for earnings data (3month, 6month, or 12month)",
  570. "enum": ["3month", "6month", "12month"],
  571. "default": "12month"
  572. },
  573. "limit": {
  574. "type": "integer",
  575. "description": "Optional: Number of earnings entries to return (default: 100)",
  576. "default": 100,
  577. "minimum": 1
  578. },
  579. "sort_by": {
  580. "type": "string",
  581. "description": "Optional: Field to sort by",
  582. "enum": ["reportDate", "symbol", "name", "fiscalDateEnding", "estimate"],
  583. "default": "reportDate"
  584. },
  585. "sort_order": {
  586. "type": "string",
  587. "description": "Optional: Sort order",
  588. "enum": ["asc", "desc"],
  589. "default": "desc"
  590. }
  591. }
  592. ```
  593. **Example Response (Default - Latest First):**
  594. ```
  595. Earnings calendar (12month):
  596. Upcoming Earnings Calendar (Sorted by reportDate desc):
  597. Company: NVDA - NVIDIA Corp
  598. Report Date: 2025-08-15
  599. Fiscal Date End: 2025-07-31
  600. Estimate: $4.25 USD
  601. ---
  602. Company: AAPL - Apple Inc
  603. Report Date: 2025-07-30
  604. Fiscal Date End: 2025-06-30
  605. Estimate: $1.85 USD
  606. ---
  607. Company: MSTR - MicroStrategy Inc
  608. Report Date: 2025-05-08
  609. Fiscal Date End: 2025-03-31
  610. Estimate: $1.30 USD
  611. ---
  612. Company: MSTR - MicroStrategy Inc
  613. Report Date: 2025-02-06
  614. Fiscal Date End: 2024-12-31
  615. Estimate: $1.25 USD
  616. ---
  617. ```
  618. **Example Response (Sorted by Symbol):**
  619. ```
  620. Earnings calendar (12month):
  621. Upcoming Earnings Calendar (Sorted by symbol asc):
  622. Company: AAPL - Apple Inc
  623. Report Date: 2025-07-30
  624. Fiscal Date End: 2025-06-30
  625. Estimate: $1.85 USD
  626. ---
  627. Company: GOOGL - Alphabet Inc
  628. Report Date: 2025-04-25
  629. Fiscal Date End: 2025-03-31
  630. Estimate: $2.15 USD
  631. ---
  632. Company: MSTR - MicroStrategy Inc
  633. Report Date: 2025-02-06
  634. Fiscal Date End: 2024-12-31
  635. Estimate: $1.25 USD
  636. ---
  637. ```
  638. ### get-historical-earnings
  639. Retrieves historical earnings data for a specific company, including both annual and quarterly reports.
  640. **Input Schema:**
  641. ```json
  642. {
  643. "symbol": {
  644. "type": "string",
  645. "description": "Stock symbol for the company (e.g., AAPL, MSFT, IBM)"
  646. },
  647. "limit_annual": {
  648. "type": "integer",
  649. "description": "Optional: Number of annual earnings to return (default: 5)",
  650. "default": 5,
  651. "minimum": 1
  652. },
  653. "limit_quarterly": {
  654. "type": "integer",
  655. "description": "Optional: Number of quarterly earnings to return (default: 8)",
  656. "default": 8,
  657. "minimum": 1
  658. }
  659. }
  660. ```
  661. **Example Response:**
  662. ```
  663. Historical Earnings for MSTR:
  664. === ANNUAL EARNINGS ===
  665. Fiscal Year End: 2023-12-31
  666. Reported EPS: $5.40
  667. ---
  668. Fiscal Year End: 2022-12-31
  669. Reported EPS: $-9.98
  670. ---
  671. === QUARTERLY EARNINGS ===
  672. Fiscal Quarter End: 2024-09-30
  673. Reported Date: 2024-10-30
  674. Reported EPS: $1.10
  675. Estimated EPS: $0.98
  676. Surprise: +$0.12 (+12.24%)
  677. Report Time: post-market
  678. ---
  679. Fiscal Quarter End: 2024-06-30
  680. Reported Date: 2024-08-01
  681. Reported EPS: $1.05
  682. Estimated EPS: $0.92
  683. Surprise: +$0.13 (+14.13%)
  684. Report Time: post-market
  685. ---
  686. ```
  687. ## Error Handling
  688. The server includes comprehensive error handling for various scenarios:
  689. - Rate limit exceeded
  690. - Invalid API key
  691. - Network connectivity issues
  692. - Timeout handling
  693. - Malformed responses
  694. Error messages are returned in a clear, human-readable format.
  695. ## Prerequisites
  696. - Python 3.12 or higher
  697. - httpx
  698. - mcp
  699. ## Contributors
  700. - [berlinbra](https://github.com/berlinbra)
  701. - [zzulanas](https://github.com/zzulanas)
  702. ## Contributing
  703. Contributions are welcome! Please feel free to submit a Pull Request.
  704. ## License
  705. This MCP server is licensed under the MIT License.
  706. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.