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:

Layer	What it does	Files
Domain	Defines TypeScript types for all data shapes	src/domain/*.types.ts
Adapters	Fetch raw JSON from upstream APIs (no processing)	src/adapters/*.adapters.ts
Services	Normalize raw data into clean domain objects	src/services/*.service.ts
MCP	Expose tools and resources to LLM clients	src/mcp/*.tools.ts

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

Upstream APIs

Endpoint	Description
GET /api/live/recent	Latest news feed with pinned stories
GET /api/wsb/latest	Wall Street Bets daily analysis snapshot
GET /api/search	Keyword-based news search
GET /api/options/chain	Options chain, GEX, and greek exposure

MCP Tools

Tool	Description	Key inputs
get_recent_news	Latest news stories	limit, offset, lang, sources, marketOnly
get_wsb_snapshot	WSB daily analysis	lang
search_news	Search news by keyword	query, limit, offset, lang, sources, sort
get_options_chain	Full options chain for a ticker	ticker, expiration, greeks
get_options_summary	Concise options exposure summary	ticker

MCP Resources

URI	Description
sellthenews://news/recent	Latest news feed (ambient context)
sellthenews://wsb/latest	Latest WSB snapshot (ambient context)

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.