finnhub

Finnhub MCP Server is a .NET-based MCP server that proxies Finnhub API data through MCP-compatible endpoints, providing a robust Symbol Search Tool and ready-to-extend infrastructure for additional tools. It emphasizes input validation, rate limiting, and secure handling of API keys. Start by configuring your Finnhub API key via environment variables, then run the server to expose HTTP endpoints for MCP tools such as symbol_search. The server is designed to scale with additional tools (e.g., Real-Time Quote, Company Profile) as they are developed, and it includes built-in retry and backoff strategies to handle Finnhub rate limits. To access the available functionality, send HTTP POST requests to the tool routes under /mcp/tools (e.g., /mcp/tools/symbol_search) with JSON payloads describing the query or parameters you need.

Key available capability: Symbol Search Tool — perform fuzzy searches for stock symbols with input validation and sanitized queries. As development progresses, additional tools (Real-Time Quote, Company Profile, Basic Financial) will be introduced and wired into the same MCP transport layer, following the same input validation and error handling patterns.

Prerequisites:

• .NET 8 SDK or later
• Finnhub API Key (free tier available)
• Git installed

Installation steps:

1. Clone the repository

git clone https://github.com/SalZaki/finnhub-mcp.git
cd finnhub-mcp

2. Restore and build the project

dotnet restore
dotnet build

3. Configure your Finnhub API key Option A - Environment Variable (recommended)

• Unix/macOS:

export FINNHUB_API_KEY="your_api_key_here"

• Windows PowerShell:

$env:FINNHUB_API_KEY="your_api_key_here"

• Windows CMD:

set FINNHUB_API_KEY=your_api_key_here

Option B - .env file (development only)

echo "FINNHUB_API_KEY=your_api_key_here" > .env

4. Run the server (HTTP transport by default)

dotnet run --project src/FinnHub.MCP.Server --urls http://localhost:5101

5. Optional: Run with STDIO transport

dotnet run --project src/FinnHub.MCP.Server -- --stdio

6. Docker (optional)

docker build -t finnhub-mcp .
docker run -e FINNHUB_API_KEY="your_api_key_here" -p 5101:5101 finnhub-mcp

Environment variables and configuration tips:

• FINNHUB_API_KEY must be set in the environment where the MCP server runs. Do not commit keys to source control.
• The server supports further configuration via appsettings.json (e.g., rate limiting, logging). See the RateLimit and Logging sections in the configuration docs within the repository.
• If you encounter 401 or 429 errors from Finnhub, verify your API key and consider adjusting rate-limiting parameters and backoff settings in your environment.
• For development, you can provide a .env file that is automatically loaded by the app during startup (not recommended for production).
• The Symbol Search Tool can be extended with additional validation rules or new search backends as needed.