Finbud Data TypeScript MCP Server

1# Finbud Data TypeScript MCP Server
2 
3It is generated with [Stainless](https://www.stainless.com/).
4 
5## Installation
6 
7### Direct invocation
8 
9You can run the MCP Server directly via `npx`:
10 
11```sh
12export FINBUD_DATA_API_KEY="My API Key"
13npx -y finbud-data-mcp
14```
15 
16### Via MCP Client
17 
18There is a partial list of existing clients at [modelcontextprotocol.io](https://modelcontextprotocol.io/clients). If you already
19have a client, consult their documentation to install the MCP server.
20 
21For clients with a configuration JSON, it might look something like this:
22 
23```json
24{
25  "mcpServers": {
26    "finbud_data_api": {
27      "command": "npx",
28      "args": ["-y", "finbud-data-mcp"],
29      "env": {
30        "FINBUD_DATA_API_KEY": "My API Key",
31        "FINBUD_DATA_BASE_URL": "https://data.finbud.ai/api"
32      }
33    }
34  }
35}
36```
37 
38## Filtering tools
39 
40You can run the package on the command line to discover and filter the set of tools that are exposed by the
41MCP Server. This can be helpful for large APIs where including all endpoints at once is too much for your AI's
42context window.
43 
44You can filter by multiple aspects:
45 
46- `--tool` includes a specific tool by name
47- `--resource` includes all tools under a specific resource, and can have wildcards, e.g. `my.resource*`
48- `--operation` includes just read (get/list) or just write operations
49 
50See more information with `--help`.
51 
52All of these command-line options can be repeated, combined together, and have corresponding exclusion versions (e.g. `--no-tool`).
53 
54Use `--list` to see the list of available tools, or see below.
55 
56## Importing the tools and server individually
57 
58```js
59// Import the server, generated endpoints, or the init function
60import { server, endpoints, init } from "finbud-data-mcp/server";
61 
62// import a specific tool
63import retrieveEstimatesAnalysts from "finbud-data-mcp/tools/analysts/retrieve-estimates-analysts";
64 
65// initialize the server and all endpoints
66init({ server, endpoints });
67 
68// manually start server
69const transport = new StdioServerTransport();
70await server.connect(transport);
71 
72// or initialize your own server with specific tools
73const myServer = new McpServer(...);
74 
75// define your own endpoint
76const myCustomEndpoint = {
77  tool: {
78    name: 'my_custom_tool',
79    description: 'My custom tool',
80    inputSchema: zodToJsonSchema(z.object({ a_property: z.string() })),
81  },
82  handler: async (client: client, args: any) => {
83    return { myResponse: 'Hello world!' };
84  })
85};
86 
87// initialize the server with your custom endpoints
88init({ server: myServer, endpoints: [retrieveEstimatesAnalysts, myCustomEndpoint] });
89```
90 
91## Available Tools
92 
93The following tools are available in this MCP server.
94 
95### Resource `analysts`:
96 
97- `retrieve_estimates_analysts` (`read`): Fetches analyst estimates (revenue, EPS) for a given company stock symbol.
98- `retrieve_price_targets_analysts` (`read`): Fetches analyst price target data for a given company stock symbol.
99- `retrieve_recommendations_analysts` (`read`): Fetches analyst stock recommendations (buy, hold, sell ratings) for a given company stock symbol.
100 
101### Resource `charts`:
102 
103- `retrieve_historical_charts` (`read`): Fetches historical intraday chart data for a specific company stock symbol and timeframe. Optional query parameters allow specifying a date range ('from', 'to') and requesting extended hours data ('extended').
104 
105### Resource `company.revenue_segmentation`:
106 
107- `retrieve_by_geography_company_revenue_segmentation` (`read`): Fetches a breakdown of a company's revenue by geographic segment for a given stock symbol, optionally filtered by period (annual/quarter).
108- `retrieve_by_product_company_revenue_segmentation` (`read`): Fetches a breakdown of a company's revenue by product segment for a given stock symbol, optionally filtered by period (annual/quarter).
109 
110### Resource `earnings`:
111 
112- `get_calendar_earnings` (`read`): Fetches the earnings calendar for a specified date range or the next few days.
113- `get_transcripts_earnings` (`read`): Fetches the earnings call transcripts for a given company stock symbol, optionally filtered by year or quarter.
114 
115### Resource `economics`:
116 
117- `get_calendar_economics` (`read`): Fetches a calendar of upcoming or past economic events (e.g., CPI release, FOMC meeting) for a specified date range.
118- `get_indicator_data_economics` (`read`): Fetches historical data for a specific economic indicator (e.g., real GDP, CPI, unemployment rate). The indicator name should be provided in kebab-case (e.g., 'real-gdp').
119 
120### Resource `etf`:
121 
122- `retrieve_holdings_etf` (`read`): Fetches the underlying holdings for a specific Exchange Traded Fund (ETF) symbol.
123 
124### Resource `financials`:
125 
126- `retrieve_balance_sheet_financials` (`read`): Fetches the 10 most recent annual balance sheet statements for a given company stock symbol.
127- `retrieve_cash_flow_financials` (`read`): Fetches the 10 most recent annual cash flow statements for a given company stock symbol.
128- `retrieve_financial_score_financials` (`read`): Fetches the financial score for a given company stock symbol. The score provides a quick assessment of a company's financial health.
129- `retrieve_income_statement_financials` (`read`): Fetches the 10 most recent annual income statements for a given company stock symbol.
130- `retrieve_key_metrics_financials` (`read`): Fetches the 10 most recent annual key metrics for a given company stock symbol.
131- `retrieve_ratios_financials` (`read`): Fetches the 10 most recent annual financial ratios for a given company stock symbol.
132 
133### Resource `government.congress`:
134 
135- `retrieve_disclosure_government_congress` (`read`): Fetches data from financial disclosures made by members of the U.S. House of Representatives. Can be filtered by stock symbol.
136- `retrieve_trading_government_congress` (`read`): Fetches data on stock trades made by U.S. Senators, as reported in Periodic Transaction Reports (PTRs). Can be filtered by stock symbol.
137 
138### Resource `insider_trading`:
139 
140- `retrieve_insider_trading` (`read`): Fetches insider trading data for a specific company stock symbol.
141 
142### Resource `market.overview`:
143 
144- `list_active_market_overview` (`read`): Fetches a list of the stocks with the highest trading volume for the day.
145- `list_gainers_market_overview` (`read`): Fetches a list of the stocks with the highest percentage gain for the day.
146- `list_losers_market_overview` (`read`): Fetches a list of the stocks with the largest percentage loss for the day.
147 
148### Resource `news`:
149 
150- `retrieve_crypto_news` (`read`): Fetches recent news articles related to the cryptocurrency market.
151- `retrieve_forex_news` (`read`): Fetches recent news articles related to the Forex market.
152- `retrieve_stock_news` (`read`): Fetches recent news articles for a given company stock symbol or multiple symbols.
153 
154### Resource `options`:
155 
156- `retrieve_quotes_options` (`read`): Retrieves historical quotes (NBBO - National Best Bid and Offer) for a specified options contract over a defined time range.
157  Includes bid/ask prices, sizes, exchange IDs, and timestamps. Max 50,000 results per request.
158- `retrieve_technical_indicator_options` (`read`): Retrieves historical technical indicator data (SMA, EMA, MACD, RSI) for a specified options ticker.
159  Query parameters vary based on the selected indicator.
160 
161### Resource `options.snapshot`:
162 
163- `retrieve_chain_options_snapshot` (`read`): Retrieves a comprehensive snapshot of all options contracts for a specified underlying asset ticker.
164  This consolidates key metrics like pricing, greeks, IV, quotes, trades, and open interest.
165- `retrieve_contract_options_snapshot` (`read`): Retrieves a comprehensive snapshot for a specific options contract identifier.
166  Consolidates vital metrics like break-even price, day changes, IV, open interest, greeks, last quote/trade, and underlying asset info.
167- `retrieve_unified_options_snapshot` (`read`): Retrieves a snapshot of the latest market data for one or more option contract tickers.
168  This typically includes last trade, last quote, day's aggregate data, and previous day's aggregate data.
169 
170### Resource `options.trades`:
171 
172- `retrieve_options_trades` (`read`): Retrieves comprehensive, tick-level trade data for a specified options ticker within a defined time range.
173  Includes price, size, exchange, conditions, and precise timestamps. Max 50,000 results per request.
174- `retrieve_last_options_trades` (`read`): Retrieves the most recent trade for a specified options ticker symbol.
175 
176### Resource `quotes`:
177 
178- `retrieve_quotes` (`read`): Fetches the real-time full stock quote(s) for one or more comma-separated company stock symbols.
179 
180### Resource `search`:
181 
182- `general_search_search` (`read`): Search for various financial instruments including stocks, ETFs, forex, and cryptocurrencies by name or symbol across different exchanges.
183 
184### Resource `technicals`:
185 
186- `retrieve_indicator_data_technicals` (`read`): Fetches historical technical indicator data for a specific stock symbol, indicator type, and time interval. Supports various indicators like SMA, EMA, WMA, DEMA, TEMA, Williams %R, RSI, ADX, and Standard Deviation. Specific required parameters depend on the chosen indicator (e.g., 'period' is required for most).
187