sp500-mcp-server
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.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 11 Nov 2026.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/zhensherlock/sp500-mcp-server with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/zhensherlock/sp500-mcp-server'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/zhensherlock--sp500-mcp-server)HTML
<a href="/listings/zhensherlock--sp500-mcp-server"><img src="/api/listings/zhensherlock--sp500-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Prerequisites
- Node.js 22 - 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.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 167 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.
- # 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](apps/web/PLAYGROUND.md)
- ## 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:
- ```sh
- pnpm install
- ```
- 2. 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.
- 3. Build the embedded MCP App HTML resources:
- ```sh
- pnpm --filter @apps/web-app build
- ```
- 4. Start the apps:
- ```sh
- 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
- ```sh
- 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:
- ```sh
- 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:
- ```sh
- pnpm --filter @apps/web-app build
- pnpm dev
- pnpm test
- ```
- Run a single tool test:
- ```sh
- pnpm vitest run apps/web/tests/tools/get-company-info-tool.test.ts
- ```
- Generate coverage:
- ```sh
- pnpm coverage
- ```
- ## Project Layout
- ```text
- 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](https://github.com/zhensherlock/sp500-mcp-server/issues/new/choose) or submit PRs.
- Standard Readme follows the [Contributor Covenant](http://contributor-covenant.org/version/1/3/0/) 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](LICENSE) © MichaelSun
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.