Sp500

zhensherlock108stars

An MCP server and Next.js web app for querying S&P 500 company data from Supabase, with tools for company info, news, officers, and SEC filings, plus embedded MCP App UI resources, Elicitation, and Sa

Databases Finance

Install Run on PlugMCP

GitHub Website

Run on PlugMCP

1# Sp500

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
License: AGPL-3.0
Last checked: 2026-10-26

Stars: 108
Tools: —
Uptime: —

Overview

About Sp500

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install Sp500?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Sp500 need an API key?

No required environment variable is listed on this record.

What transport does Sp500 use?

Sp500 runs locally over stdio.

When was Sp500 last checked?

Last checked 2026-10-26. An MCP server and Next.js web app for querying S&P 500 company data from Supabase, with tools for company info, news, officers, and SEC filings, plus embedded MCP App UI resources, Elicitation, and Sampling support.

From the publisher

Documentation

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:

pnpm install

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.

Build the embedded MCP App HTML resources:

pnpm --filter @apps/web-app build

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.

License

GNU Affero General Public License v3.0 © MichaelSun

Sp500

zhensherlock108stars

Databases Finance

Install Run on PlugMCP

GitHub Website

Run on PlugMCP

1# Sp500

README.mdMCP server

Transport: stdio
Status: Local

Power your agent

Add this server

Install from the publisher. Not a PlugMCP endpoint.

Run on PlugMCP

Host a copy with our keys and logs.

No packaged release in the registry yet. Follow the repository README.

RepositoryPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
License: AGPL-3.0
Last checked: 2026-10-26

Stars: 108
Tools: —
Uptime: —

Overview

About Sp500

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

How do I install Sp500?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Sp500 need an API key?

No required environment variable is listed on this record.

What transport does Sp500 use?

Sp500 runs locally over stdio.

When was Sp500 last checked?

From the publisher

Documentation

S&P 500 MCP Server

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

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:

pnpm install

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.

Build the embedded MCP App HTML resources:

pnpm --filter @apps/web-app build

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.