Alpha Vantage MCP Server

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