stackoverflow-fastmcp 1.3.0

StackOverflow MCP server for querying programming Q&A using FastMCP framework

StackOverflow MCP Server

A Model Context Protocol (MCP) server that provides seamless access to StackOverflow's programming Q&A database using the FastMCP framework.

Quick Start

Using with Cursor (Recommended)

Add this configuration to your Cursor MCP settings:

{
  "mcp_servers": {
    "stackoverflow": {
      "command": "npx",
      "args": [
        "-y",
        "@notalk-tech/stackoverflow-mcp",
        "--api-key", "your_stackoverflow_api_key"
      ]
    }
  }
}

Using NPX

# Run directly (no installation required)
npx @notalk-tech/stackoverflow-mcp

# With API key
npx @notalk-tech/stackoverflow-mcp --api-key your_key

# Skip installation prompts
npx -y @notalk-tech/stackoverflow-mcp

Using Python Module

# Direct execution
python -m stackoverflow_mcp

# With uv (recommended)
uv run python -m stackoverflow_mcp --api-key your_key

🎯 Features

• 🔍 Advanced Search: Search by keywords, tags, accepted status, score threshold, and date ranges
• 📖 Question Details: Get detailed content with automatic HTML-to-Markdown conversion
• 🏷️ Tag-based Search: Convenient tag-only search (proxies to main search)
• 💡 Related Questions: Discover related and linked questions for deeper exploration
• ⚡ Rate Limit Management: Intelligent retry, backoff, and auto-switching between authenticated/unauthenticated access
• 🔐 API Authentication: Full support for StackOverflow API keys with automatic quota tracking
• 📦 Unified Response Format: All tools return consistent {success, data, meta} structure
• 🚀 Auto-deployment: NPX-compatible with automatic Python environment setup

🔑 Getting Your API Key

To use this MCP server with higher rate limits, you'll need a StackOverflow API key:

Steps

1. Register Your Application

   • Visit https://stackapps.com/applications/register
   • Log in with your Stack Exchange account
   • Fill in application details (name, description, OAuth domain)
   • Submit the registration

2. Generate Your API Key

   • Go to your application management page
   • Click "Generate a new API key"
   • Copy and save the generated key securely

Rate Limits

• Without API key: 300 requests/day per IP
• With API key: 10,000 requests/day

For read-only operations (searching and retrieving Q&A), a simple API key is sufficient. OAuth is only needed for write operations.

Learn more: https://api.stackexchange.com/docs/authentication

⚙️ Configuration

Create a .stackoverflow-mcp.json file in your working directory:

{
  "stackoverflow_api_key": "your_api_key_here",
  "log_level": "CRITICAL"
}

The server auto-discovers config files in this order:

1. .stackoverflow-mcp.json
2. stackoverflow-mcp.config.json
3. config/stackoverflow-mcp.json
4. .config/stackoverflow-mcp.json

Command Line Options

--working-dir DIRECTORY    Working directory (auto-detect if not specified)
--api-key TEXT             StackOverflow API key
--version                  Show version and exit
--help                     Show help message

🌐 Available Tools

Once running, the MCP server provides these tools:

• search_questions: Search StackOverflow questions by keywords with optional filters — tags, accepted_only, min_score, from_date, to_date
• search_by_tags: Convenience wrapper for tag-only search (proxies to search_questions)
• get_question: Get detailed question content with optional answer limiting (max_answers) and automatic HTML-to-Markdown conversion
• get_answers: Fetch answers independently without re-fetching the question body
• get_related: Discover related and linked questions for further exploration

Resource

• stackoverflow://status: Server status including version, authentication state, rate limit status, and queue statistics

📋 Prerequisites

• Node.js 14.0.0 or higher
• Python 3.12 or higher
• uv (recommended) or pip

The NPX wrapper automatically handles Python package installation and environment setup.

🚀 Development

Local Setup

git clone https://github.com/NoTalkTech/stackoverflow-mcp.git
cd stackoverflow-mcp

# Install dependencies
npm install
pip install -e .

# Run in development mode
npm start

Project Structure

stackoverflow-mcp/
├── cli.js                          # NPX wrapper (Node.js)
├── package.json                    # NPM package configuration
├── pyproject.toml                  # Python package configuration
├── src/stackoverflow_mcp/          # Python MCP server
│   ├── __main__.py                 # Python module entry point
│   ├── main.py                     # CLI and server management
│   ├── server.py                   # MCP server implementation (5 tools + resource)
│   ├── config.py                   # Server configuration management
│   ├── logging.py                  # Logging configuration
│   └── stackoverflow_client.py     # StackOverflow API client (rate limiting, caching, content formatting)
└── tests/                          # Test files

Testing

# Run all tests
.venv/bin/python -m pytest tests/ -v

# Test npm package
npm test

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🆘 Support

• Issues: GitHub Issues
• Documentation: GitHub README

🙏 Acknowledgments

• Model Context Protocol for the MCP specification
• StackOverflow for providing the API
• The open-source community for inspiration and contributions

---

Made for the developer community