Sp500 MCP Server

S&P 500 MCP Server

<p align="center"> <img src="assets/readme-poster.png" alt="S&P 500 MCP promotional poster" width="100%" /> </p>

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 24 (.nvmrc; required by Eve)
• 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
• Agent playground: Eve, direct OpenAI access, and interactive MCP Apps at /playground; see setup and architecture

Getting Started

Prerequisites

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

Local Development

1. Install dependencies:

pnpm install

2. Create a local env file with Supabase credentials:

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.

3. Build the embedded MCP App HTML resources:

pnpm --filter @apps/web-app build

4. Start the apps:

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

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:

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:

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

Run a single tool test:

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

Generate coverage:

pnpm coverage

Project Layout

apps/web/
  app/mcp/route.ts              MCP Streamable HTTP GET/POST handler
  app/[transport]/tools/        MCP tool registrations
  app/[transport]/utils/        Supabase and symbol resolution
  app/api/tools/call/route.ts   HTTP proxy for the web tool tester
  app/tools/                    Tool catalog page
  components/                   App-specific UI
  tests/tools/                  MCP integration tests
apps/web-app/
  src/pages/                    Embedded MCP App pages, one per tool
  src/components/               MCP App UI components
  scripts/build-pages.js        Builds each page into dist/*.html
  dist/                         Generated single-file HTML resources
packages/ui/
  src/components/               Shared shadcn UI primitives
  src/styles/globals.css        Shared Tailwind CSS

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.

Vercel Deployment

• The /mcp handler is stateless and does not require Redis
• Modern 2026-07-28 and legacy 2025 Streamable HTTP clients use the same endpoint

Docs

Full guides and examples: https://sp500-mcp.vercel.app/

Contributing

Feel free to dive in! Open an issue or submit PRs.

Standard Readme follows the Contributor Covenant Code of Conduct.

Contributors

This project exists thanks to all the people who contribute.

<a href="https://github.com/zhensherlock/sp500-mcp-server/graphs/contributors"> <img src="https://contrib.rocks/image?repo=zhensherlock/sp500-mcp-server" /> </a>

License

GNU Affero General Public License v3.0 © MichaelSun