README.md•4.25 kB
# Marketstack MCP Server
A Model Context Protocol (MCP) server that exposes various Marketstack API endpoints as MCP tools, providing access to financial data including end-of-day, intraday, splits, dividends, tickers, exchanges, currencies, timezones, bonds, and ETF data. This server simplifies integrating Marketstack data into MCP-compatible agents and systems.
## Prerequisites
- Node.js (v18 or later recommended)
- npm (comes with Node.js)
- Marketstack API key
- (Optional) MCP-compatible client or runner (e.g., VSCode extension, CLI)
## Setup
1. **Clone the repository or ensure you are in the project directory.**
2. **Install dependencies:**
```bash
npm install
```
3. **Configuration:**
* Obtain a Marketstack API key from [https://marketstack.com/](https://marketstack.com/).
* Configure the `MARKETSTACK_API_KEY` environment variable via your MCP runner's settings. This is the recommended method for seamless integration with the MCP client. Avoid using `.env` files for this purpose when running via an MCP runner.
## Building and Running
1. **Build the server:**
```bash
npm run build
```
This will create a `build` directory with the compiled JavaScript code.
2. **Run the server:**
```bash
npm run start
```
or directly:
```bash
node build/index.js
```
3. **Via MCP runner:**
Configure your MCP client to run the server using stdio transport.
Example MCP settings entry (adjust `/path/to/mcp-marketstack` to your actual path and replace `YOUR_API_KEY_HERE` with your actual key):
```json
"marketstack": {
"transportType": "stdio",
"command": "node",
"args": [
"/path/to/mcp-marketstack/build/index.js"
],
"env": {
"MARKETSTACK_API_KEY": "YOUR_API_KEY_HERE"
}
// ... other optional settings ...
}
```
## Available Tools
The server exposes Marketstack API endpoints as distinct MCP tools, categorized by function:
- Market Data
- Reference Data
- Financial Instruments
Detailed input schemas and descriptions for each tool are automatically discoverable by MCP agents connecting to the server via introspection.
## Project Structure
The project follows a modular structure:
```
.
├── src/
│ ├── index.ts # Server entry point
│ ├── marketstackClient.ts # Centralized API client with caching
│ ├── cacheConfig.ts # Cache TTL configurations
│ └── tools/
│ ├── index.ts # Registers all tool categories
│ ├── marketData/ # Market Data tools
│ │ └── ...
│ ├── referenceData/ # Reference Data tools
│ │ └── ...
│ ├── financialInstruments/ # Financial Instruments tools
│ │ └── ...
│ └── wrapToolHandler.ts # Wrapper for tool handlers
├── memory-bank/ # Project documentation
│ └── ...
├── package.json # Project dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── eslint.config.js # ESLint configuration
├── .prettierrc # Prettier configuration
├── LICENSE # Project license
└── README.md # This file
```
## Caching
The server implements an in-memory Least Recently Used (LRU) cache for tool responses. This helps reduce redundant calls to the Marketstack API, improving performance and adhering to rate limits.
- **Mechanism:** The cache stores responses based on the tool name and input parameters.
- **Configurable TTLs:** Each tool has a configurable Time To Live (TTL) for its cached data, defined in `src/cacheConfig.ts`. This allows for different caching durations based on the update frequency of the data provided by each Marketstack endpoint.
## Licensing
This project is licensed under the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. See the `LICENSE` file for details.
## Contributing
Contributions are welcome! Please follow the standard fork-and-pull request workflow.
## Support
For issues or questions, please open an issue on the GitHub repository.