# 📰 FinanceNews MCP

[![npm version](https://badge.fury.io/js/financenews-mcp.svg)](https://badge.fury.io/js/financenews-mcp)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](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

```bash
npm install -g financenews-mcp
```

### Install from source

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

## 🚀 Quick Start

### 1. Start the MCP Server

```bash
# 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):

```json
{
  "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:

```env
# 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

```bash
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:

1. **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)

1. Copy the environment template:
```bash
cp env-example.txt .env
```

2. Edit the `.env` file and add your Finnhub API key:
```env
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

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

### Development Scripts

```bash
# 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

1. Open Claude Desktop settings
2. Navigate to "Developer" tab
3. Add the MCP server configuration:

```json
{
  "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:

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

## 📊 Production Deployment

### Docker

```dockerfile
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

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

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

### Development Workflow

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

## 📄 License

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

## 👨‍💻 Author

**Xingyu Chen**
- 📧 Email: [guangxiangdebizi@gmail.com](mailto:guangxiangdebizi@gmail.com)
- 🔗 LinkedIn: [Xingyu Chen](https://www.linkedin.com/in/xingyu-chen-b5b3b0313/)
- 🐙 GitHub: [@guangxiangdebizi](https://github.com/guangxiangdebizi)
- 📦 NPM: [@xingyuchen](https://www.npmjs.com/~xingyuchen)

## 🙏 Acknowledgments

- [Model Context Protocol](https://modelcontextprotocol.io/) for the excellent protocol specification
- [Anthropic](https://www.anthropic.com/) 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>