cyanheads/stackexchange-mcp-server

imageVersion imageLicense imageDocker imageMCP SDK imagenpm imageTypeScript imageBun

imageInstall in Claude Desktop imageInstall in Cursor imageInstall in VS Code

imageFramework

Public Hosted Server: https://stackexchange.caseyjhand.com/mcp

Overview

Stack Overflow and the rest of the Stack Exchange network, from Super User and Server Fault to Unix & Linux. Search questions, read complete Q&A threads as clean markdown, browse tag FAQs, and look up user profiles.

Tools

Agent skill

skills/stackexchange-guide covers what the tool schemas don't: why IDs never carry across sites and which site a URL or ID is read from, search syntax for error messages and tags, choosing which answer to quote, and what each call costs against the daily quota. Plugin installs (Claude Code, Codex) and the Claude Desktop bundle load it from the package, and MCP clients that support the Skills extension read it from the server through skills/list.

Capability reference

stackexchange_search_questions tool

• Full-text query with optional tag filters, minimum score threshold, and accepted-only filter; sort by relevance (default), votes, activity, or newest
• Up to 30 results per page (default 10); page for more — each page costs one API quota unit, and paging past 25 requires STACKEXCHANGE_API_KEY
• Returns question ID, title, score, answer count, tags, and a ~300-character excerpt — IDs flow directly into stackexchange_get_thread
• Quota remaining and max surfaced via enrichment on every response
• Every response reports appliedSort, the order Stack Exchange actually used; minScore forces votes, and sortOverrideReason says so whenever that replaces the requested sort

stackexchange_get_thread tool

• Accepts a numeric question ID or a full Stack Exchange question URL; fetches the question and a page of maxAnswers answers (1–100, default 10), adding the accepted answer if it falls outside that page
• A URL is read from the site its host names (unix.stackexchange.com, ru.stackoverflow.com, arqade.com, …), so site applies only to a numeric ID or a hostless /questions/ path; a site naming a different site than the URL is ignored, and a URL whose host is not a Stack Exchange site (a translation proxy) is read from site instead — either way reported as siteConflict on both surfaces. Such a URL sent without site fails as invalid_site
• HTML→markdown normalization built in — code blocks, links, lists, headers, and blockquotes all converted
• Optional includeComments fetches up to 20 comments per post, newest first, using two extra API calls (one when there are no answers); commentsTruncated reports partial lists
• Attribution (author name, profile link, score) on every answer per CC BY-SA 4.0
• Quota remaining and max surfaced via enrichment; truncated when more answers exist upstream than maxAnswers returned

stackexchange_get_tag_faq tool

• A tag's frequently asked questions — maps to /tags/{tag}/faq, Stack Exchange's own selection, returned in its order and not sorted by score
• Up to 30 results per page (default 10); page for more — each page costs one API quota unit, and paging past 25 requires STACKEXCHANGE_API_KEY
• Returns a question list without bodies; pipe any questionId into stackexchange_get_thread for full content
• Quota remaining and max surfaced via enrichment on every response

stackexchange_get_user tool

• userId must be at most 2,147,483,647 (32-bit) — typically the authorUserId from stackexchange_get_thread output
• Fetches the profile and top tags in two upstream API calls
• Returns reputation, badge counts (gold/silver/bronze), location, website, answer/question counts, and up to 10 top tags by answer score (empty array for users with no answers)
• An unknown user ID returns a typed user_not_found error — Stack Exchange answers HTTP 200 with empty results rather than 404

stackexchange_list_sites tool

• Fetches every site in the Stack Exchange network, walking pages of 100 up to a 10-page cap; an enrichment notice flags a partial list if the network still has more
• Optional case-insensitive name filter matches against site name and api_site_parameter, applied client-side after the fetch
• Returns the api_site_parameter value (e.g. stackoverflow, superuser, serverfault) that every other tool's site parameter accepts; the site's domain (e.g. serverfault.com) works there too

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Stack Exchange-specific:

• HTML→markdown conversion preserves code blocks, tables, links, images, and nested lists
• Shared upstream queue honors response backoff, stated throttle waits, and HTTP 429 cooldowns; each operation has a 50-second budget covering queue time, backoff, requests, and retries, a backoff that cannot fit it fails at once, and a queued call sheds before the budget ends, both with retryAfter instead of running out the clock
• Quota logging: quota_remaining and quota_max surfaced via enrichment on every tool call
• Typed error contracts on every tool — invalid_site, invalid_parameter, invalid_api_key, invalid_id_or_url, invalid_user_id, question_not_found, user_not_found, paging_depth_limit, quota_exceeded, throttled, pacer_shed, and upstream_unavailable
• Optional STACKEXCHANGE_API_KEY lifts the per-IP quota from ~300/day to ~10,000/day with no OAuth required

Agent-friendly output:

• Quota remaining on every response — agents can plan around rate limits without the server needing to fail
• The accepted answer appears first, followed by the remaining answers sorted by score
• Each answer includes attribution under CC BY-SA 4.0
• Typed not_found errors for missing questions and users (SE returns HTTP 200 with empty items[] rather than 404)

Getting started

Connect to the hosted instance, no install:

claude mcp add --transport http stackexchange-mcp-server https://stackexchange.caseyjhand.com/mcp

Or run it locally:

claude mcp add stackexchange-mcp-server -- npx -y @cyanheads/stackexchange-mcp-server

For other clients, add this to the MCP config file:

{
  "mcpServers": {
    "stackexchange-mcp-server": {
      "command": "npx",
      "args": ["-y", "@cyanheads/stackexchange-mcp-server"]
    }
  }
}

Without a key, the Stack Exchange API allows ~300 requests/day per IP; set STACKEXCHANGE_API_KEY to lift this to ~10,000/day. Register a key at stackapps.com/apps/oauth/register — a key alone covers read-only use. For Docker or a source build, see Running the server.

Configuration

See .env.example for the full list of optional overrides.

Running the server

Local development

Requires Bun v1.4.0 or higher (or Node.js v24+).

• Clone and install:

  git clone https://github.com/cyanheads/stackexchange-mcp-server.git
  cd stackexchange-mcp-server && bun install
  cp .env.example .env   # optionally set STACKEXCHANGE_API_KEY
  

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker run --rm -e STACKEXCHANGE_API_KEY=your-key -p 3010:3010 ghcr.io/cyanheads/stackexchange-mcp-server:latest

The image defaults to HTTP transport, stateless session mode, and logs to /var/log/stackexchange-mcp-server. To run it over stdio from an MCP client, use "command": "docker" with "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/stackexchange-mcp-server:latest"]. To build locally, docker build -t stackexchange-mcp-server .; OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Development guide

See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools via the barrel in src/mcp-server/tools/definitions/index.ts
• Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.