Sp500 Mcp Server

What is Sp500 MCP Server about?

A server and web application that expose a set of MCP tools for retrieving detailed information about S&P 500 companies—including basic profile, financials, recent news with sentiment analysis, officer compensation, and SEC filing history—backed by a Supabase database.

How to use Sp500 MCP Server?

1. Prerequisites: Node.js 22, pnpm 10, and a Supabase project containing the required S&P 500 tables.
2. Install dependencies: pnpm install.
3. Configure environment: create a .env file with SUPABASE_URL, SUPABASE_ANON_KEY, optionally REDIS_URL and MCP_MAX_DURATION.
4. Run locally: pnpm dev starts the Next.js app at http://localhost:3000 and the MCP endpoint at http://localhost:3000/mcp.
5. Call tools: Send GET/POST/DELETE requests to /mcp using the MCP protocol, or interact via the built‑in web UI at /tools.
6. Testing: With the dev server running, execute pnpm test or run individual tool tests via Vitest.

Key Features

• Four core MCP tools: get_company_info, get_company_news, get_company_officers, get_company_filings.
• Next.js 15 App Router with React 19 and strict TypeScript.
• Shared UI library built on shadcn/ui and Tailwind for a consistent look.
• TurboRepo + pnpm workspace for fast monorepo development.
• Production‑ready deployment on Vercel with Fluid compute and optional Redis‑backed SSE.
• Integration tests that hit the live MCP endpoint.

Use Cases

• Building finance‑focused chatbots or assistants that need real‑time company data.
• Creating dashboards or analytics tools that query fundamentals, news sentiment, or filing histories.
• Developing research applications that compare executive compensation across the S&P 500.
• Serving as a backend for educational platforms teaching financial data analysis.

FAQ

Q: Do I need a Supabase account? A: Yes, the server reads all company data from Supabase tables. Provide the URL and anon key in the .env file.

Q: Is Redis mandatory? A: No. Redis (REDIS_URL) is only required for Server‑Sent Events in production. Local development works without it.

Q: How can I extend the tool set? A: Add a new TypeScript file under apps/web/app/[transport]/tools/ and register it in the MCP handler (route.ts). The framework will expose it automatically.

Q: What is the maximum execution time? A: Controlled by MCP_MAX_DURATION (default 60 seconds). Increase it on Vercel if your plan supports longer Fluid compute durations.

Q: Can I run the server with npm instead of pnpm? A: Yes, but the repository assumes pnpm 10 for workspace linking. Use npm install and equivalent scripts if preferred.

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, news sentiment, officers, and SEC filings, plus a web UI for browsing and testing those tools.

Tools

Tool	Description
get_company_info	Company basics, financials, leadership, address, and business summary
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.

Tech Stack

• Workspace: pnpm 10 + Turborepo
• Runtime: Node 22 (.nvmrc)
• App: Next.js 15 App Router, React 19, TypeScript strict mode (apps/web)
• MCP: mcp-handler at apps/web/app/[transport]/route.ts; /mcp is the active endpoint
• 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

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
MCP_MAX_DURATION=60
REDIS_URL=your_redis_url

SUPABASE_URL and SUPABASE_ANON_KEY are required. REDIS_URL is only needed for production SSE.

3. Start the Next.js app:

pnpm dev

The web app runs on http://localhost:3000; the MCP endpoint is http://localhost:3000/mcp.

Commands

pnpm dev        # Start apps/web via Turbo
pnpm build      # Production build for apps/web
pnpm start      # Start production server for apps/web
pnpm lint       # ESLint + Prettier rule checks

Type-check the packages directly:

pnpm exec tsc -p apps/web/tsconfig.json --noEmit
pnpm exec tsc -p packages/ui/tsconfig.json --noEmit

pnpm type-check currently calls tsc --noEmit without a root tsconfig.json, so it exits with TypeScript help instead of checking the app.

Testing

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

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/[transport]/route.ts      MCP GET/POST/DELETE handler
  app/[transport]/tools/        MCP tool registrations
  app/[transport]/utils/        Supabase, symbol resolution, summaries
  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
packages/ui/
  src/components/               Shared shadcn UI primitives
  src/styles/globals.css        Shared Tailwind CSS

Vercel Deployment

• Requires Fluid compute
• MCP_MAX_DURATION defaults to 60; set a higher duration for long-running production calls when your Vercel plan supports it
• SSE is enabled (disableSse: false); production SSE requires Redis via REDIS_URL

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