StackOverflow MCP server for querying programming Q&A using FastMCP - npx wrapper for Python package
npm install @luqezman/stackoverflow-mcpbash
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`)