mcp-marketstack

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:

   npm install
   

3. Configuration:

   • Obtain a Marketstack API key from 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:

   npm run build
   

   This will create a build directory with the compiled JavaScript code.

2. Run the server:

   npm run start
   

   or directly:

   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):

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