openspec-mcp-x
Advanced tools
Model Context Protocol server for OpenSpec - AI-powered API specification tool
OpenSpec MCP Server for Cursor IDE - AI-powered API specification generation and management. Now available as an NPX package for easy installation!
OpenSpec is an AI-powered tool for generating, managing, and validating API specifications. This MCP server provides seamless integration with Cursor IDE.
The easiest way to use OpenSpec MCP is via NPX. No manual installation required!
Open or create ~/.cursor/mcp.json:
Windows: C:\Users\<YourUsername>\.cursor\mcp.json
macOS/Linux: ~/.cursor/mcp.json
Add the OpenSpec MCP configuration:
{
"mcpServers": {
"openspec": {
"command": "npx",
"args": ["-y", "openspec-mcp-x@latest"],
"env": {}
}
}
}
⚠️ If you already have other MCP servers, add the "openspec" entry to your existing "mcpServers" object (don't replace the entire file).
Completely quit and restart Cursor IDE.
In Cursor, ask the AI:
Check OpenSpec installation status
That's it! The NPX package will automatically:
OpenSpec MCP requires the OpenSpec CLI tool. Install it with:
npm install -g @fission-ai/openspec
Verify installation:
openspec --version
For running the MCP server.
Check if installed:
python --version
# or
python3 --version
If not installed or version is below 3.10:
brew install python@3.12 or download from https://www.python.org/downloads/Required for OpenSpec CLI to work.
Check if installed:
node --version
npm --version
If not installed, follow the installation guide for your platform:
⚠️ IMPORTANT FOR WINDOWS: All commands below include non-interactive flags to avoid installation prompts. This is crucial when AI assistants execute these commands.
Method 1: winget (Recommended - Windows 10+)
# Install Node.js LTS with non-interactive flags
# These flags prevent interactive prompts that would block automated installation
winget install OpenJS.NodeJS.LTS --accept-package-agreements --accept-source-agreements
# After installation, restart your terminal and verify
node --version
npm --version
Method 2: Chocolatey
# Install Node.js LTS with -y flag to skip confirmation
choco install nodejs-lts -y
# Verify installation
node --version
npm --version
Method 3: Scoop
# Scoop is non-interactive by default
scoop install nodejs-lts
node --version
npm --version
Method 4: Manual Download
node --version and npm --version📝 Note: After installation on Windows, you MUST restart your terminal or IDE for the PATH environment variable to be updated. If commands still don't work, restart your computer.
Method 1: Homebrew (Recommended)
# Install Homebrew if not installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Install Node.js LTS
brew install node@20
# Verify installation
node --version
npm --version
Method 2: nvm (Node Version Manager)
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# Restart terminal or reload shell configuration
source ~/.bashrc # or ~/.zshrc for zsh
# Install Node.js LTS
nvm install --lts
nvm use --lts
# Verify installation
node --version
npm --version
Method 3: Manual Download
node --version and npm --versionAfter installing Node.js and npm, verify the installation:
# Check Node.js version (should be 18.x or higher)
node --version
# Check npm version
npm --version
# Optional: Update npm to latest version
npm install -g npm@latest
Windows - Command not found after installation:
node --versionmacOS - Permission errors with npm:
# Fix npm permissions for global packages
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile
Verify PATH:
C:\Program Files\nodejs\/usr/local/bin/ or /opt/homebrew/bin/The IDE this MCP server integrates with.
If you're an AI assistant helping users set up OpenSpec MCP, follow this automated workflow:
First, detect the platform and check what's already installed:
# Windows: Check winget availability
winget --version
# macOS: Check if Homebrew is available
brew --version
Check each requirement:
# Check Python (required: 3.10+)
python --version || python3 --version
# Check Node.js (required: 18.x+)
node --version
# Check npm (bundled with Node.js)
npm --version
# Check pip (Python package manager)
pip --version || pip3 --version
Based on detection results, use the appropriate commands from the platform-specific sections above.
⚠️ CRITICAL FOR WINDOWS: ALWAYS use non-interactive flags to prevent installation prompts!
# If Node.js/npm is missing, use winget with non-interactive flags:
winget install OpenJS.NodeJS.LTS --accept-package-agreements --accept-source-agreements
# Alternative with Chocolatey (if available):
choco install nodejs-lts -y
# After installation, MUST restart terminal or commands won't be found
# Remind user to close and reopen terminal/IDE
# Then verify installation:
node --version
npm --version
Why non-interactive flags are essential on Windows:
--accept-package-agreements: Auto-accepts package license agreements--accept-source-agreements: Auto-accepts source agreements (e.g., Microsoft Store terms)# Ensure Homebrew is installed first
brew --version || /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Install Node.js if needed
brew install node@20
# Verify
node --version
npm --version
After ensuring Node.js and npm are installed:
# Install OpenSpec globally
npm install -g @fission-ai/openspec
# Verify OpenSpec installation
openspec --version
Important for Windows users:
openspec command is not found after installation, the user needs to restart their terminalC:\Users\<Username>\AppData\Roaming\npmOnce all prerequisites are confirmed, continue with the Installation section below.
For Windows:
--accept-package-agreements --accept-source-agreementsFor macOS:
python3 and pip3 commands (not python and pip)General:
The NPX method is the easiest and doesn't require manual installation. See the Quick Start section above.
If you prefer to install manually or need a development setup:
First, check which Python command works on your system:
# Try these commands one by one:
python --version
python3 --version
Remember which command works (either python or python3), you'll need it in step 3.
Navigate to the openspec-mcp directory and install:
cd D:\Tools\0mcp\openspec-mcp
pip install -e .
All platforms: ~/.cursor/mcp.json
~/.cursor/mcp.jsonC:\Users\<YourUsername>\.cursor\mcp.json💡 Tip: This is Cursor's main MCP configuration file, shared by all MCP servers.
Option A: If the configuration file does NOT exist (first MCP server):
Create the file ~/.cursor/mcp.json with this content:
{
"mcpServers": {
"openspec": {
"command": "REPLACE_WITH_YOUR_PYTHON_COMMAND",
"args": ["-m", "openspec_mcp.server"],
"env": {}
}
}
}
⚠️ Replace REPLACE_WITH_YOUR_PYTHON_COMMAND with the command you verified in step 1 (python or python3).
Option B: If the configuration file ALREADY exists (adding to existing MCP servers):
⚠️ DO NOT replace the entire file! Only add the "openspec" entry inside the existing "mcpServers" object.
Example - if your current config has other servers:
{
"mcpServers": {
"some-other-server": {
"command": "...",
"args": ["..."],
"env": {}
}
}
}
Add the openspec entry like this (add a comma after the previous server):
{
"mcpServers": {
"some-other-server": {
"command": "...",
"args": ["..."],
"env": {}
},
"openspec": {
"command": "REPLACE_WITH_YOUR_PYTHON_COMMAND",
"args": ["-m", "openspec_mcp.server"],
"env": {}
}
}
}
⚠️ Remember to replace REPLACE_WITH_YOUR_PYTHON_COMMAND with your verified Python command.
✅ Multiple MCP servers can coexist in the same configuration file!
Completely quit and restart Cursor.
After installation (either NPX or manual method), verify in Cursor:
Check OpenSpec installation status
Or use the tool directly:
Use check_openspec_status tool
This will confirm:
check_openspec_status - Check if OpenSpec is installed and get version infoopenspec_init - Initialize OpenSpec in a directoryopenspec_generate - Generate API specificationopenspec_validate - Validate an API specification fileopenspec_help - Get help information about OpenSpec commandsUse check_openspec_status tool
This will check if OpenSpec CLI is installed and show version info.
Make sure Node.js and npm are installed first (see Requirements section).
Install OpenSpec CLI using npm:
npm install -g @fission-ai/openspec
Verify installation:
openspec --version
Use openspec_init tool with:
- directory: ./my-project
Use openspec_generate tool with:
- directory: ./my-project
- output: ./api/openapi.yaml
- format: openapi
Use openspec_validate tool with:
- file_path: ./api/openapi.yaml
Install Node.js and npm (if not already installed):
Install OpenSpec CLI (first time only):
npm install -g @fission-ai/openspec
Check installation:
Use check_openspec_status tool
Initialize in your project:
Use openspec_init tool with directory: ./my-project
Generate specifications:
Use openspec_generate tool with directory: ./my-project
Validate specifications:
Use openspec_validate tool with file_path: ./api/spec.yaml
python --version or python3 --version (must be 3.10+)# Upgrade pip
python -m pip install --upgrade pip
# Clear cache
pip cache purge
# Reinstall
pip install -e .
1. Check if Node.js and npm are installed:
node --version
npm --version
If not found, install Node.js from https://nodejs.org/ or use package managers (see Requirements).
2. Install OpenSpec CLI:
npm install -g @fission-ai/openspec
3. Verify installation:
openspec --version
4. Test with MCP:
Use check_openspec_status tool
# Use npx instead, or fix npm permissions:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.profile
source ~/.profile
OpenSpec can be configured through its configuration files. After running openspec_init, you'll find configuration files in your project directory.
Refer to the OpenSpec documentation for detailed configuration options.
MIT
# Install globally (optional)
npm install -g openspec-mcp-x
# Or use directly with NPX (recommended)
npx openspec-mcp-x@latest
See CHANGELOG.md for version history and updates.
For maintainers:
# First-time publish
./publish.sh
# Update version and publish
./update.sh
For issues related to:
FAQs
Model Context Protocol server for OpenSpec - AI-powered API specification tool
The npm package openspec-mcp-x receives a total of 12 weekly downloads. As such, openspec-mcp-x popularity was classified as not popular.
We found that openspec-mcp-x demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
OSV withdrew 157 OSV malware reports after automated false positives incorrectly flagged trusted npm and PyPI packages, sending bad records into tools that rely on OSV data.
Research
/Security News
TrapDoor crypto stealer hits 36 malicious packages across npm, PyPI, and Crates.io, targeting crypto, DeFi, AI, and security developers.
Research
/Security News
Laravel Lang packages were compromised with an RCE backdoor across hundreds of versions, exposing cloud, CI/CD, and developer secrets.