StackOverflow MCP Server

A Model Context Protocol (MCP) server that provides seamless access to StackOverflow's programming Q&A database using the FastMCP framework. This package serves as an NPX-compatible wrapper for the Python-based StackOverflow MCP server.

Quick Start

Using NPX (Recommended)

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

# Skip installation prompts (useful for automation)
npx -y @notalk-tech/stackoverflow-mcp

# Or install globally
npm install -g @notalk-tech/stackoverflow-mcp
stackoverflow-mcp

Using Python Module Directly

# If you have the Python package installed
python -m stackoverflow_mcp

# Using uv (recommended for Python development)
uv run python -m stackoverflow_mcp

Integrating with Cursor

To add StackOverflow MCP as a Model Context Protocol server in Cursor, add the following configuration to your Cursor settings:

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

📋 Prerequisites

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

The NPX wrapper will automatically:

Detect your Python installation
Install the required Python package (stackoverflow-fastmcp)
Handle environment setup and configuration

Installation

Option 1: NPX (No Installation)

npx @notalk-tech/stackoverflow-mcp --help

Option 2: Global NPM Installation

npm install -g @notalk-tech/stackoverflow-mcp
stackoverflow-mcp --help

Option 3: Local Development

git clone https://github.com/NoTalkTech/stackoverflow-mcp.git
cd stackoverflow-mcp
npm install
node cli.js --help

🎯 Features

🔍 Question Search: Search StackOverflow questions by keywords
📖 Question Details: Get detailed question content, answers, and metadata
🏷️ Tag-based Search: Find questions by programming language tags
⚡ Rate Limit Management: Automatic detection and handling of API limits
🔐 API Authentication: Support for StackOverflow API keys
🚀 Auto-deployment: NPX-compatible with automatic Python environment setup
📁 Smart Configuration: Auto-discovery of config files and working directories
🔧 Development Mode: Enhanced logging and debugging features
⚡ FastMCP Implementation: Simplified, elegant server using FastMCP framework

About MCP Mode

This server is specifically designed to operate in Model Context Protocol (MCP) mode, which means:

Communication occurs through standard input/output (stdio) rather than HTTP
The server integrates seamlessly with AI assistants supporting the MCP standard
No traditional server ports or network connections are used
The server provides a consistent, structured interface for querying StackOverflow

MCP mode makes this tool ideal for integration with AI models, allowing them to search and retrieve programming knowledge programmatically.

Usage

Basic Usage

# Start the MCP server with default settings
npx @notalk-tech/stackoverflow-mcp

# Auto-confirm installation (useful for scripts/CI)
npx -y @notalk-tech/stackoverflow-mcp

# Provide an API key directly
npx @notalk-tech/stackoverflow-mcp --api-key your_stackoverflow_api_key

# Specify a working directory
npx @notalk-tech/stackoverflow-mcp --working-dir /path/to/your/project

Python Development with uv

For Python development, we recommend using uv for faster dependency management:

# Install dependencies with uv
uv sync

# Run the server with uv
uv run python -m stackoverflow_mcp

# Run with API key
uv run python -m stackoverflow_mcp --api-key your_stackoverflow_api_key

FastMCP Benefits:

🔥 Simplified Code: Clean, maintainable implementation
🎯 Decorator-based: Clean tool registration with @mcp.tool()
🚀 Auto-schema: Type hints automatically generate schemas
🛡️ Built-in Error Handling: Consistent error responses
📦 Better Separation: Clean architecture with focused responsibilities

Configuration

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

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

Command Line Options

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

🔧 Configuration Files

The server automatically discovers configuration files in the following order:

.stackoverflow-mcp.json
stackoverflow-mcp.config.json
config/stackoverflow-mcp.json
.config/stackoverflow-mcp.json

🌐 API Endpoints

Once running, the MCP server provides the following tools:

search_questions: Search StackOverflow questions by keywords
search_by_tags: Find questions filtered by programming language tags
get_question: Get detailed information about a specific question
get_question_with_answers: Get comprehensive question details including answers
get_rate_limit_status: Get current rate limiting status and quotas
get_authentication_status: Get current API authentication status
get_queue_status: Get current request queue status and statistics

🧪 Testing

# Test the npm package
npm test

# Test npm packaging
npm run test:npm

# Test global installation
npm run test:install

# Test Python module directly
python -m pytest tests/ -v

🚀 Development

Local Development Setup

# Clone the repository
git clone https://github.com/NoTalkTech/stackoverflow-mcp.git
cd stackoverflow-mcp

# Install Node.js dependencies
npm install

# Install Python dependencies
pip install -e .

# Run in development mode
npm start

Project Structure

@notalk/stackoverflow-mcp/
├── cli.js                          # NPX wrapper (Node.js)
├── package.json                    # NPM 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
│   └── stackoverflow_client.py     # StackOverflow API client
├── tests/                          # Test files
└── README.md                       # This file

📦 Publishing

Semantic Versioning

This package follows Semantic Versioning:

MAJOR: Breaking changes
MINOR: New features (backward compatible)
PATCH: Bug fixes (backward compatible)

Current Versions

Python Package: stackoverflow-fastmcp v0.2.6
NPM Package: @notalk-tech/stackoverflow-mcp v1.2.5

Version Synchronization

When publishing new versions, it's important to keep version numbers synchronized:

Python Package Version: Defined in src/stackoverflow_mcp/__init__.py and pyproject.toml
NPM Package Version: Defined in package.json
CLI Version Reference: Defined in cli.js (expectedVersion variable)

All three should be updated together when making a release to ensure consistency.

Release Process

This project provides a unified publishing script to simultaneously release both NPM and Python packages.

# Option 1: Using the publish script (recommended)
./publish.sh             # Publish both NPM and Python packages
./publish.sh --npm-only  # Publish only the NPM package
./publish.sh --pypi-only # Publish only the Python package
./publish.sh --dry-run   # Test the publishing process without actual uploads

# Option 2: Manual process
# Update version
npm version patch|minor|major

# Publish to npm
npm publish

# Create GitHub release
git push --tags

Prerequisites for Publishing

PyPI API token (environment variable PYPI_API_TOKEN or configured in ~/.pypirc)
NPM authentication (npm login or using automation tokens)
Git credentials for pushing tags

🤝 Contributing

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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 Wiki
Discussions: GitHub Discussions

🙏 Acknowledgments

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

Made with ❤️ for the developer community

Name		Name	Last commit message	Last commit date
Latest commit History 75 Commits
.ai		.ai
examples		examples
src/stackoverflow_mcp		src/stackoverflow_mcp
tests		tests
.gitignore		.gitignore
.npmignore		.npmignore
.python-version		.python-version
.stackoverflow-mcp.example.json		.stackoverflow-mcp.example.json
.stackoverflow-mcp.json		.stackoverflow-mcp.json
LICENSE		LICENSE
README.md		README.md
cli.js		cli.js
package-lock.json		package-lock.json
package.json		package.json
publish.sh		publish.sh
pyproject.toml		pyproject.toml
uv.lock		uv.lock

License

NoTalkTech/stackoverflow-mcp

Folders and files

Latest commit

History

Repository files navigation

StackOverflow MCP Server

Quick Start

Using NPX (Recommended)

Using Python Module Directly

Integrating with Cursor

📋 Prerequisites

Installation

Option 1: NPX (No Installation)

Option 2: Global NPM Installation

Option 3: Local Development

🎯 Features

About MCP Mode

Usage

Basic Usage

Python Development with uv

Configuration

Command Line Options

🔧 Configuration Files

🌐 API Endpoints

🧪 Testing

🚀 Development

Local Development Setup

Project Structure

📦 Publishing

Semantic Versioning

Current Versions

Version Synchronization

Release Process

Prerequisites for Publishing

🤝 Contributing

License

🆘 Support

🙏 Acknowledgments

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages