sp500-mcp-server

Free

S&P 500 MCP Server An MCP (Model Context Protocol) server and Next.js web app for querying S&P 500 company data from Supabase. It exposes M…

106 stars0 likes1 views

Website GitHub

About

S&P 500 MCP Server An MCP (Model Context Protocol) server and Next.js web app for querying S&P 500 company data from Supabase. It exposes M…

S&P 500 MCP Server

An MCP (Model Context Protocol) server and Next.js web app for querying S&P 500 company data from Supabase. It exposes MCP tools for company fundamentals, annual financial metrics, historical price data, news sentiment, officers, and SEC filings, plus a web UI and embedded MCP App resources for browsing and testing those tools.

Tools

Tool	Description
`get_company_info`	Company basics, financials, leadership, address, and business summary
`get_company_financials`	Annual financial metrics with chart-ready trends and matrix output
`get_company_price_data`	Historical daily OHLCV price rows with date filters
`get_company_news`	Recent company news with sentiment filtering
`get_company_officers`	Executive officers and compensation
`get_company_filings`	SEC filings history, with filing type and date filters

search_companies is an internal symbol resolver, not an exposed MCP tool. User queries are resolved through getCompanySymbol. For ambiguous matches, elicitation-capable clients are asked to choose a company. Modern clients receive an input_required result; the SDK compatibility layer serves the same flow to 2025-era Streamable HTTP clients. Clients without elicitation support continue with the first match.

Tech Stack

Workspace: pnpm 10.34.5 + Turborepo
Runtime: Node 22 (.nvmrc)
Web app: Next.js 16 App Router, React 19, TypeScript strict mode (apps/web)
MCP Apps: Vite single-file React pages built from apps/web-app and served as tool UI resources
MCP: mcp-handler v2 at apps/web/app/mcp/route.ts; /mcp serves modern and legacy Streamable HTTP
Database: Supabase client at apps/web/app/[transport]/utils/supabase.ts
UI: shared shadcn/Tailwind primitives in packages/ui

Getting Started

Prerequisites

Node.js 22
pnpm 10
Supabase project with the S&P 500 data tables used by the tools

Local Development

Install dependencies:

bash

pnpm install

Create a local env file with Supabase credentials:

env

SUPABASE_URL=your_supabase_url
SUPABASE_ANON_KEY=your_supabase_anon_key
LOGO_DEV_TOKEN=your_logo_dev_publishable_key

SUPABASE_URL and SUPABASE_ANON_KEY are required. LOGO_DEV_TOKEN is required for the /api/logo/* proxy.

Build the embedded MCP App HTML resources:

bash

pnpm --filter @apps/web-app build

Start the apps:

bash

pnpm dev

The Next.js web app runs on http://localhost:3000; the MCP endpoint is http://localhost:3000/mcp. The apps/web-app dev server proxies /mcp to port 3000 when run separately.

Commands

bash

pnpm dev        # Start apps/* dev tasks via Turbo
pnpm build      # Build apps/web and apps/web-app via Turbo
pnpm start      # Start production server for apps/web
pnpm type-check # Type-check apps/web and apps/web-app
pnpm lint       # ESLint + Prettier rule checks

Focused commands:

bash

pnpm --filter @apps/web dev
pnpm --filter @apps/web-app dev
pnpm --filter @apps/web-app build
pnpm exec tsc -p apps/web/tsconfig.json --noEmit
pnpm exec tsc -p apps/web-app/tsconfig.json --noEmit
pnpm exec tsc -p packages/ui/tsconfig.json --noEmit

Testing

Tests are integration tests that connect a real MCP client to http://localhost:3000/mcp, so start the dev server first:

bash

pnpm --filter @apps/web-app build
pnpm dev
pnpm test

Run a single tool test:

bash

pnpm vitest run apps/web/tests/tools/get-company-info-tool.test.ts

Generate coverage:

bash

pnpm coverage

Project Layout

…

apps/web/app/[transport]/tools/app-resource.ts reads generated HTML from apps/web-app/dist, so rebuild apps/web-app after changing embedded MCP App pages.