sellthenews-mcp

A read-only MCP (Model Context Protocol) server that wraps sellthenews.org API endpoints, making financial news and options data available as tools for LLMs like Claude.

Architecture

sellthenews.org API  →  Adapters  →  Services  →  MCP Tools & Resources

Four layers, each with one job:

Data flows left to right: the MCP layer calls services, services call adapters, adapters call the HTTP client.

Upstream APIs

MCP Tools

MCP Resources

Setup

npm install
npm run build

Run Locally

npm start

The server runs over stdio, so it is meant to be launched by an MCP client such as Claude Desktop or an MCP inspector rather than opened in a browser.

For private single-user compatibility testing, the HTTP client can also read SELLTHENEWS_USER_AGENT, SELLTHENEWS_COOKIE, SELLTHENEWS_ACCEPT_LANGUAGE, and SELLTHENEWS_REFERER from the environment and forward them as request headers when present.

Usage with Claude Desktop

Add this to your Claude Desktop MCP config file. On macOS it's at ~/Library/Application Support/Claude/claude_desktop_config.json, on Windows it's at %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "sellthenews": {
      "command": "node",
      "args": ["/REPLACE/WITH/YOUR/ACTUAL/PATH/sellthenews_MCP/dist/index.js"]
    }
  }
}

Important: Replace the path above with the actual absolute path to dist/index.js on your machine. For example, on Windows it might be C:\\Users\\yourname\\Desktop\\sellthenews_MCP\\dist\\index.js.

Project Structure

src/
  domain/
    shared.types.ts       # Common types (SourceInfo, TickerMention, etc.)
    news.types.ts         # News domain: raw API types + clean domain types
    options.types.ts      # Options domain: raw API types + clean domain types
  infra/
    http-client.ts        # HTTP client wrapping fetch()
  adapters/
    news.adapters.ts      # 3 news adapters (live/recent, wsb, search)
    options.adapters.ts   # 1 options adapter (options/chain)
  services/
    news.service.ts       # News normalization logic
    options.service.ts    # Options normalization logic
  mcp/
    news.tools.ts         # News MCP tools + resources + Zod schemas
    options.tools.ts      # Options MCP tools + Zod schemas
  index.ts                # Entry point: wires layers, starts server

Current Status

Stage 2A is complete. The repository now performs real upstream GET requests, normalizes raw responses into domain objects, and exposes live MCP tools/resources that return consistent JSON text.

Implemented now:

1. HttpClient.get() with URL building, timeout handling, JSON parsing, and clearer error messages
2. Real adapters for all four identified sellthenews endpoints
3. Service-layer normalization for news feeds, WSB snapshots, options chains, and options summaries
4. Live MCP tool and resource handlers wired to the service layer
5. Optional env-driven compatibility headers for private single-user testing when plain server-side requests hit upstream protection

Still pending:

1. Automated tests for adapters, services, and MCP smoke coverage
2. Better operational hardening if upstream failures or Cloudflare issues show up in practice
3. Stage 3 concerns such as caching, rate limiting, and production logging

Quick Smoke Check

1. Run npm run build
2. Run npm start
3. Connect the server from Claude Desktop or an MCP inspector
4. Call get_recent_news with { "limit": 2 } or get_options_summary with { "ticker": "MU" }

If upstream access works, the response should be pretty-printed JSON instead of placeholder text.

If upstream blocks plain server-side requests, retry your local run with SELLTHENEWS_USER_AGENT, SELLTHENEWS_COOKIE, SELLTHENEWS_ACCEPT_LANGUAGE, and SELLTHENEWS_REFERER set in the environment as needed.