Marketstack MCP Server

# 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.