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

$3

``bash

Run directly with npx (no installation required)

npx @luqezman/stackoverflow-mcp

Skip installation prompts (useful for automation)

npx -y @luqezman/stackoverflow-mcp

Or install globally

npm install -g @luqezman/stackoverflow-mcp
stackoverflow-mcp
`

$3

`bash

If you have the Python package installed

python -m stackoverflow_mcp

Using uv (recommended for Python development)

uv run python -m stackoverflow_mcp
`

$3

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

`json
{
"mcp_servers": {
"stackoverflow": {
"command": "npx",
"args": [
"-y",
"@luqezman/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

$3

`bash
npx @luqezman/stackoverflow-mcp --help
`

$3

`bash
npm install -g @luqezman/stackoverflow-mcp
stackoverflow-mcp --help
`

$3

`bash
git clone https://github.com/lucasmonstrox/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

$3

`bash

Start the MCP server with default settings

npx @luqezman/stackoverflow-mcp

Auto-confirm installation (useful for scripts/CI)

npx -y @luqezman/stackoverflow-mcp

Provide an API key directly

npx @luqezman/stackoverflow-mcp --api-key your_stackoverflow_api_key

Specify a working directory

npx @luqezman/stackoverflow-mcp --working-dir /path/to/your/project
`

$3

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

`bash

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

$3

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

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

$3

`
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:

1. .stackoverflow-mcp.json
2. stackoverflow-mcp.config.json
3. config/stackoverflow-mcp.json
4. .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

`bash

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

$3

`bash

Clone the repository

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

Install Node.js dependencies

npm install

Install Python dependencies

pip install -e .

Run in development mode

npm start
`

$3

`
@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

$3

This package follows Semantic Versioning:

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

$3

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

$3

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

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

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

$3

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

`bash

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

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 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