📰 FinanceNews MCP

![npm version](https://badge.fury.io/js/financenews-mcp) ![License: Apache-2.0](https://opensource.org/licenses/Apache-2.0) ![Node.js](https://nodejs.org/)

A Model Context Protocol (MCP) server that provides financial news search capabilities. This server enables AI assistants to fetch and analyze financial news from various sources based on user queries.

✨ Features

🔍 Smart News Search: Query financial news with natural language
📊 Real-time Updates: Get the latest financial news and market updates
🌐 Finnhub Integration: Fetches real-time news from Finnhub financial data platform (no fake data)
🚀 High Performance: Built with TypeScript and Express for optimal performance
🔧 Easy Integration: Simple MCP protocol implementation

🛠️ Installation

Prerequisites

Node.js 18.0.0 or higher
npm or yarn package manager

Install from npm

npm install -g financenews-mcp

Install from source

git clone https://github.com/guangxiangdebizi/FinanceNews-MCP.git
cd FinanceNews-MCP
npm install
npm run build

🚀 Quick Start

1. Start the MCP Server

# Using npm global install
financenews-mcp

# Or from source
npm run start:http

The server will start on http://localhost:3000 by default.

2. Configure Your AI Client

Add the following configuration to your MCP client (e.g., Claude Desktop):

{
  "mcpServers": {
    "financenews-mcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3000/mcp",
      "timeout": 600
    }
  }
}

3. Start Using

Once configured, you can ask your AI assistant to search for financial news:

"Search for Apple earnings news"
"Find news about Federal Reserve interest rates"
"Get cryptocurrency market updates"

🔧 Available Tools

`get_financial_news`

Fetches financial news based on a search query.

Parameters:

query (string, required): Search query for financial news topics

Example Usage: ``json { "name": "get_financial_news", "arguments": { "query": "Tesla stock earnings" } } ``

📡 API Endpoints

MCP Endpoint: POST /mcp - Main MCP protocol endpoint
Health Check: GET /health - Server health status

🔧 Configuration

Environment Variables

Create a .env file in the project root:

# Server Configuration
PORT=3000
NODE_ENV=development

# API Keys (for production use)
# NEWS_API_KEY=your_news_api_key
# ALPHA_VANTAGE_API_KEY=your_alpha_vantage_key

# Rate Limiting
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100

# Cache Configuration
CACHE_TTL_SECONDS=300

# Logging
LOG_LEVEL=info

Custom Port

PORT=8080 npm run start:http

🔑 Finnhub API Configuration

Getting Your Finnhub API Key

To fetch real financial news, you need to configure a Finnhub API key:

Finnhub (finnhub.io)

Free tier: 60 requests/minute
Sign up at: https://finnhub.io/register
Get your API key from the dashboard after registration

Configuration Options

You have two ways to configure your Finnhub API key:

Option 1: Environment Variable (Recommended for personal use)

Copy the environment template:

cp env-example.txt .env

Edit the .env file and add your Finnhub API key:

FINNHUB_API_KEY=your_actual_finnhub_key

Option 2: MCP Headers (Recommended for shared/team use)

Add headers directly to your MCP client configuration. This is useful when you want different API keys for different clients or when you can't modify environment variables.

Claude Desktop Configuration: ``json { "mcpServers": { "financenews-mcp": { "type": "streamableHttp", "url": "http://localhost:3000/mcp", "headers": { "X-Finnhub-API-Key": "your_actual_finnhub_key" } } } } ``

Supported Header Names:

X-Finnhub-API-Key (recommended)
X-API-Key
Authorization: Bearer your_key (standard Bearer token format)

Error Handling

API Key Missing: If no Finnhub API key is configured, the tool will display clear instructions on how to obtain and configure the API key
No Results: If Finnhub API doesn't return any results for your query, the tool will suggest alternative search terms
Network Errors: Any network or API errors will be clearly communicated with helpful troubleshooting information

The tool does not use sample or fake data - it only returns real news from Finnhub or clear error messages.

🏗️ Development

Setup Development Environment

git clone https://github.com/guangxiangdebizi/FinanceNews-MCP.git
cd FinanceNews-MCP
npm install
cp .env.example .env

Development Scripts

# Build the project
npm run build

# Start development server
npm run dev

# Start production server
npm run start:http

# Clean build directory
npm run clean

Project Structure

src/
├── index.ts              # MCP server main entry point
└── tools/
    └── financial-news.ts  # Financial news search tool

🔌 Integration Examples

Claude Desktop

Open Claude Desktop settings
Navigate to "Developer" tab
Add the MCP server configuration:

{
  "mcpServers": {
    "financenews-mcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "X-Finnhub-API-Key": "your_actual_finnhub_key"
      }
    }
  }
}

Custom Headers (Optional)

For authentication or tenant identification:

{
  "mcpServers": {
    "financenews-mcp": {
      "type": "streamableHttp",
      "url": "http://localhost:3000/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_TOKEN",
        "X-Tenant-Id": "your_tenant_id"
      }
    }
  }
}

📊 Production Deployment

Docker

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY build/ ./build/
EXPOSE 3000
CMD ["npm", "run", "start:http"]

PM2

npm install -g pm2
pm2 start build/index.js --name "financenews-mcp"

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development Workflow

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes and add tests
Commit your changes: git commit -m 'Add amazing feature'
Push to the branch: git push origin feature/amazing-feature
Open a Pull Request

📄 License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

👨‍💻 Author

Xingyu Chen

📧 Email: guangxiangdebizi@gmail.com
🔗 LinkedIn: Xingyu Chen
🐙 GitHub: @guangxiangdebizi
📦 NPM: @xingyuchen

🙏 Acknowledgments

Model Context Protocol for the excellent protocol specification
Anthropic for Claude and MCP development
The open-source community for inspiration and contributions

📈 Roadmap

[ ] Real-time news API integrations
[ ] Advanced filtering and categorization
[ ] Sentiment analysis for news articles
[ ] Historical news data access
[ ] Multi-language support
[ ] News summarization capabilities

---

<div align="center"> <p>Made with ❤️ by <a href="https://github.com/guangxiangdebizi">Xingyu Chen</a></p> <p>⭐ Star this repo if you find it helpful!</p> </div>

FinanceNews MCP