Skip to content
Back to search

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.

Checked today

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zhensherlock--sp500-mcp-server/badge.svg)](/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

i

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.

  1. # S&P 500 MCP Server
  2. <p align="center">
  3. <img src="assets/readme-poster.png" alt="S&P 500 MCP promotional poster" width="100%" />
  4. </p>
  5. 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.
  6. ## Tools
  7. | Tool | Description |
  8. | ------------------------ | --------------------------------------------------------------------- |
  9. | `get_company_info` | Company basics, financials, leadership, address, and business summary |
  10. | `get_company_financials` | Annual financial metrics with chart-ready trends and matrix output |
  11. | `get_company_price_data` | Historical daily OHLCV price rows with date filters |
  12. | `get_company_news` | Recent company news with sentiment filtering |
  13. | `get_company_officers` | Executive officers and compensation |
  14. | `get_company_filings` | SEC filings history, with filing type and date filters |
  15. `search_companies` is an internal symbol resolver, not an exposed MCP tool. User queries are resolved through `getCompanySymbol`.
  16. For ambiguous matches, elicitation-capable clients are asked to choose a company. Modern clients receive an `input_required`
  17. result; the SDK compatibility layer serves the same flow to 2025-era Streamable HTTP clients. Clients without elicitation
  18. support continue with the first match.
  19. ## Tech Stack
  20. - **Workspace**: pnpm 10.34.5 + Turborepo
  21. - **Runtime**: Node 24 (`.nvmrc`; required by Eve)
  22. - **Web app**: Next.js 16 App Router, React 19, TypeScript strict mode (`apps/web`)
  23. - **MCP Apps**: Vite single-file React pages built from `apps/web-app` and served as tool UI resources
  24. - **MCP**: `mcp-handler` v2 at `apps/web/app/mcp/route.ts`; `/mcp` serves modern and legacy Streamable HTTP
  25. - **Database**: Supabase client at `apps/web/app/[transport]/utils/supabase.ts`
  26. - **UI**: shared shadcn/Tailwind primitives in `packages/ui`
  27. - **Agent playground**: Eve, direct OpenAI access, and interactive MCP Apps at `/playground`; see [setup and architecture](apps/web/PLAYGROUND.md)
  28. ## Getting Started
  29. ### Prerequisites
  30. - Node.js 24
  31. - pnpm 10
  32. - Supabase project with the S&P 500 data tables used by the tools
  33. ### Local Development
  34. 1. Install dependencies:
  35. ```sh
  36. pnpm install
  37. ```
  38. 2. Create a local env file with Supabase credentials:
  39. ```env
  40. SUPABASE_URL=your_supabase_url
  41. SUPABASE_ANON_KEY=your_supabase_anon_key
  42. LOGO_DEV_TOKEN=your_logo_dev_publishable_key
  43. ```
  44. `SUPABASE_URL` and `SUPABASE_ANON_KEY` are required. `LOGO_DEV_TOKEN` is required for the `/api/logo/*` proxy.
  45. 3. Build the embedded MCP App HTML resources:
  46. ```sh
  47. pnpm --filter @apps/web-app build
  48. ```
  49. 4. Start the apps:
  50. ```sh
  51. pnpm dev
  52. ```
  53. 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.
  54. ## Commands
  55. ```sh
  56. pnpm dev # Start apps/* dev tasks via Turbo
  57. pnpm build # Build apps/web and apps/web-app via Turbo
  58. pnpm start # Start production server for apps/web
  59. pnpm type-check # Type-check apps/web and apps/web-app
  60. pnpm lint # ESLint + Prettier rule checks
  61. ```
  62. Focused commands:
  63. ```sh
  64. pnpm --filter @apps/web dev
  65. pnpm --filter @apps/web-app dev
  66. pnpm --filter @apps/web-app build
  67. pnpm exec tsc -p apps/web/tsconfig.json --noEmit
  68. pnpm exec tsc -p apps/web-app/tsconfig.json --noEmit
  69. pnpm exec tsc -p packages/ui/tsconfig.json --noEmit
  70. ```
  71. ## Testing
  72. Tests are integration tests that connect a real MCP client to `http://localhost:3000/mcp`, so start the dev server first:
  73. ```sh
  74. pnpm --filter @apps/web-app build
  75. pnpm dev
  76. pnpm test
  77. ```
  78. Run a single tool test:
  79. ```sh
  80. pnpm vitest run apps/web/tests/tools/get-company-info-tool.test.ts
  81. ```
  82. Generate coverage:
  83. ```sh
  84. pnpm coverage
  85. ```
  86. ## Project Layout
  87. ```text
  88. apps/web/
  89. app/mcp/route.ts MCP Streamable HTTP GET/POST handler
  90. app/[transport]/tools/ MCP tool registrations
  91. app/[transport]/utils/ Supabase and symbol resolution
  92. app/api/tools/call/route.ts HTTP proxy for the web tool tester
  93. app/tools/ Tool catalog page
  94. components/ App-specific UI
  95. tests/tools/ MCP integration tests
  96. apps/web-app/
  97. src/pages/ Embedded MCP App pages, one per tool
  98. src/components/ MCP App UI components
  99. scripts/build-pages.js Builds each page into dist/*.html
  100. dist/ Generated single-file HTML resources
  101. packages/ui/
  102. src/components/ Shared shadcn UI primitives
  103. src/styles/globals.css Shared Tailwind CSS
  104. ```
  105. `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.
  106. ## Vercel Deployment
  107. - The `/mcp` handler is stateless and does not require Redis
  108. - Modern 2026-07-28 and legacy 2025 Streamable HTTP clients use the same endpoint
  109. ## Docs
  110. Full guides and examples: https://sp500-mcp.vercel.app/
  111. ## Contributing
  112. Feel free to dive in! [Open an issue](https://github.com/zhensherlock/sp500-mcp-server/issues/new/choose) or submit PRs.
  113. Standard Readme follows the [Contributor Covenant](http://contributor-covenant.org/version/1/3/0/) Code of Conduct.
  114. ### Contributors
  115. This project exists thanks to all the people who contribute.
  116. <a href="https://github.com/zhensherlock/sp500-mcp-server/graphs/contributors">
  117. <img src="https://contrib.rocks/image?repo=zhensherlock/sp500-mcp-server" />
  118. </a>
  119. ## License
  120. [GNU Affero General Public License v3.0](LICENSE) © MichaelSun

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.