Provides access to Cisco Support APIs including Bug Search, Case Management, End-of-Life information, PSIRT security vulnerability data, Product information, and Software recommendations through 33 tools across 6 different Cisco APIs.
Offers alternative endpoint compatibility for N8N integration, allowing the MCP server to be used with N8N automation workflows.
Cisco Support MCP Server
A production-ready TypeScript MCP (Model Context Protocol) server for Cisco Support APIs with comprehensive security and dual transport support. This extensible server provides access to multiple Cisco Support APIs including Bug Search, Case Management, and End-of-Life information.
🚀 Current Features
Multi-API Support: 6 Cisco Support APIs fully implemented (33 total tools)
Bearer Token Authentication: MCP Inspector-style security for HTTP endpoints
Configurable API Access: Enable only the Cisco Support APIs you have access to
Specialized Prompts: 9 workflow prompts for guided Cisco support scenarios
Dual Transport: stdio (local MCP clients) and HTTP (remote server with auth)
OAuth2 Authentication: Automatic token management with Cisco API
Real-time Updates: Server-Sent Events for HTTP mode
TypeScript: Full type safety and MCP SDK integration
Production Security: Helmet, CORS, input validation, Bearer tokens
Docker Support: Containerized deployment with health checks
Comprehensive Logging: Structured logging with timestamps
📊 Supported Cisco APIs
The server supports the following Cisco Support APIs (configurable via SUPPORT_API
environment variable):
API | Status | Tools | Description |
Enhanced Analysis (
) | ⭐ RECOMMENDED | 6 tools | Advanced analysis tools for comprehensive product assessment |
Bug (
) | ✅ Complete | 14 tools | Bug Search, Details, Product-specific searches + Enhanced tools |
Case (
) | ✅ Complete | 4 tools | Support case management and operations |
EoX (
) | ✅ Complete | 4 tools | End of Life/Sale information and lifecycle planning |
PSIRT (
) | ✅ Complete | 8 tools | Product Security Incident Response Team vulnerability data |
Product (
) | ✅ Complete | 3 tools | Product details, specifications, and technical information |
Software (
) | ✅ Complete | 6 tools | Software suggestions, releases, and upgrade recommendations |
Serial (
) | 🔄 Planned | 0 tools | Serial number to product information mapping |
RMA (
) | 🔄 Planned | 0 tools | Return Merchandise Authorization processes |
Implementation Status: 6/8 APIs complete (75%) with 33 total tools
Configuration Examples:
SUPPORT_API=enhanced_analysis
- Enhanced analysis tools only (6 tools) ← RECOMMENDED for most usersSUPPORT_API=bug
- All Bug API tools including enhanced analysis (14 tools)SUPPORT_API=bug,case,eox,psirt
- Core support APIs (28 tools)SUPPORT_API=bug,case,eox,psirt,product,software
- All implemented APIs (39 tools)SUPPORT_API=all
- All available APIs (includes 2 placeholder APIs)
Quick Start
NPX Installation (Recommended)
Start in stdio mode for Claude Desktop:
Start HTTP server with authentication:
Generate Bearer token for HTTP mode:
Get help and see all options:
Environment Setup
Generate authentication token (for HTTP mode):
npx mcp-cisco-support --generate-token export MCP_BEARER_TOKEN=<generated_token>Set Cisco API credentials:
export CISCO_CLIENT_ID=your_client_id_here export CISCO_CLIENT_SECRET=your_client_secret_here export SUPPORT_API=bug,case,eox,psirt,product,software # All implemented APIs (recommended)Start the server:
# For Claude Desktop (stdio mode) npx mcp-cisco-support # For HTTP access (with authentication) npx mcp-cisco-support --http
Local Development
Claude Desktop Integration
Prerequisites
Get Cisco API Credentials:
Visit Cisco API Console
Create an application and get your Client ID and Secret
Ensure the application has access to the Bug API
Install Claude Desktop:
Download from Claude.ai
Make sure you're using a recent version that supports MCP
Step-by-Step Setup
Locate Claude Desktop Config File:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
Windows:
%APPDATA%\Claude\claude_desktop_config.json
Create or Edit the Config File:
{ "mcpServers": { "cisco-support": { "command": "npx", "args": ["mcp-cisco-support"], "env": { "CISCO_CLIENT_ID": "your_client_id_here", "CISCO_CLIENT_SECRET": "your_client_secret_here", "SUPPORT_API": "bug" } } } }Optional: Configure which APIs to enable with
SUPPORT_API
:"enhanced_analysis"
- Enhanced analysis tools only (recommended for most users)"bug"
- Bug API only (default)"all"
- All available APIs"bug,case,eox"
- Multiple specific APIs
Replace Your Credentials:
Replace
your_client_id_here
with your actual Cisco Client IDReplace
your_client_secret_here
with your actual Cisco Client Secret
Restart Claude Desktop:
Close Claude Desktop completely
Reopen the application
The MCP server will be automatically loaded
Verification
After setup, you should be able to:
Ask Claude about Cisco bugs:
"Search for bugs related to memory leaks in Cisco switches"Get specific bug details:
"Get details for Cisco bug CSCab12345"Search by product:
"Find bugs affecting Cisco Catalyst 3560 switches"
Example Usage in Claude Desktop
Once configured, you can ask Claude questions like:
Basic Bug Search:
"Search for recent bugs related to 'crash' in Cisco products"
"Find open bugs with severity 1 or 2"
"Show me bugs modified in the last 30 days"
Product-Specific Searches:
"Find bugs for product ID C9200-24P"
"Search for bugs in Cisco Catalyst 9200 Series affecting release 17.5.1"
"Show bugs fixed in software release 17.5.2"
Bug Details:
"Get full details for bug CSCab12345"
"Show me information about bugs CSCab12345,CSCcd67890"
Advanced Filtering:
"Find resolved bugs with severity 3 modified after 2023-01-01"
"Search for bugs in 'Cisco ASR 9000 Series' sorted by severity"
"Can you show me all the cisco bugs in the last 30 days for the product Cisco Unified Communications Manager (CallManager)?" (uses keyword search)
"Find bugs for Cisco Unified Communications Manager affecting releases 14.0 and 15.0" (uses product series search)
Claude will use the appropriate MCP tools to fetch real-time data from Cisco's Bug API and provide comprehensive responses with the latest information.
MCP Prompts
The server includes 5 specialized prompts for guided Cisco support workflows:
🚨 cisco-incident-investigation - Investigate symptoms and errors
🔄 cisco-upgrade-planning - Research issues before upgrades
🔧 cisco-maintenance-prep - Prepare for maintenance windows
🔒 cisco-security-advisory - Research security vulnerabilities
⚠️ cisco-known-issues - Check for software release issues
Each prompt provides structured investigation plans and expert recommendations.
See ⚡ MCP Prompts for complete prompt documentation and examples.
Screenshots
Claude Desktop Integration
Claude Desktop successfully connected to the Cisco Support MCP server, demonstrating the bug search functionality with real-time responses from Cisco's Bug API.
MCP Inspector
MCP Inspector v0.14.0+ showing the available tools and server connectivity testing capabilities.
Alternative Installation Methods
Global Installation
If you prefer to install globally instead of using npx:
Then use this config:
Local Installation
For development or custom setups:
Then use this config:
Troubleshooting
Common Issues
"Command not found" errors:
Ensure Node.js 18+ is installed
Try global installation:
npm install -g mcp-cisco-support
Verify the path in your config file
Authentication failures:
Double-check your Client ID and Secret
Ensure your Cisco API app has Bug API access
Check for typos in the config file
MCP server not loading:
Restart Claude Desktop completely
Check the config file syntax with a JSON validator
Look for Claude Desktop logs/error messages
Permission errors:
Ensure the config file is readable
On macOS/Linux, check file permissions:
chmod 644 claude_desktop_config.json
Debugging
Test the server manually:
npx mcp-cisco-supportThis should start the server in stdio mode without errors.
Validate your config: Use a JSON validator to ensure your config file is properly formatted.
Check Claude Desktop logs:
Look for MCP-related error messages in Claude Desktop
The app usually shows connection status for MCP servers
Monitor logs in real-time (macOS):
# Follow logs in real-time tail -n 20 -F ~/Library/Logs/Claude/mcp*.logOn Windows:
# Check logs directory %APPDATA%\Claude\logs\
Getting Help
Issues: GitHub Issues
Cisco API: Cisco Developer Documentation
MCP Protocol: Model Context Protocol
Docker Deployment
🔐 Security
stdio mode: No authentication (Claude Desktop, local clients)
HTTP mode: Bearer token authentication required
See 🔒 Security Guide for complete security documentation.
Configuration
Environment Variables
Create a .env
file with your configuration:
Claude Desktop Integration
Complete configuration for Claude Desktop:
Docker Configuration
With authentication:
Without authentication (development only):
API Endpoints
Endpoint | Method | Description |
| GET | Server information and available endpoints |
| POST | Main MCP endpoint (JSON-RPC over HTTP) |
| POST | Alternative MCP endpoint for N8N compatibility |
| GET | SSE connection with session management |
| POST | Legacy SSE message endpoint (deprecated) |
| POST | Session-specific MCP message endpoint |
| GET | Simple ping endpoint for connectivity testing |
| GET | Health check with detailed status |
📚 Documentation
For detailed information, see our comprehensive GitHub Wiki:
📋 Available Tools - Complete reference for all 33 MCP tools across 6 APIs
🔧 Advanced Configuration - Environment variables and deployment options
🔒 Security Guide - Authentication, tokens, and security best practices
🚀 Docker Deployment - Containerized deployment and production setup
🌐 SSE Integration - Server-Sent Events and real-time communication
🧪 Testing Framework - Comprehensive testing and validation
🔧 Development Guide - Contributing, architecture, and API development
🚨 Troubleshooting Guide - Common issues and debugging
⚡ MCP Prompts - Guided workflows for Cisco support scenarios
Usage Examples
cURL Examples
JavaScript Client Example
Health Monitoring
The server provides a comprehensive health check endpoint:
Response includes:
Server status
OAuth2 token status
Memory usage
Uptime
Active SSE connections
Security Features
Helmet: Security headers
CORS: Cross-origin resource sharing
Input Validation: Schema-based validation
Non-root Execution: Docker security
Environment Variables: Secure credential storage
Troubleshooting
Common Issues
OAuth2 Authentication Failed
Verify
CISCO_CLIENT_ID
andCISCO_CLIENT_SECRET
Check network connectivity to
https://id.cisco.com
API Calls Failing
Check token validity at
/health
Verify network access to
https://apix.cisco.com
Docker Issues
Ensure environment variables are set
Check Docker logs:
docker-compose logs
Logs
Structured JSON logs include:
Timestamp
Log level (info, error, warn)
Message
Additional context data
Testing
Running Tests
Test Structure
The test suite includes:
Authentication Tests (
tests/auth.test.js
): OAuth2 authentication, token management, error handlingMCP Tools Tests (
tests/mcp-tools.test.js
): All 8 MCP tools, error handling, paginationSetup (
tests/setup.js
): Test environment configuration
Recent Test Fixes
The following issues were identified and resolved in the test suite:
✅ Fixed Issues
Token Refresh Logic
Problem: Token expiry calculation was incorrect in
getValidToken()
Solution: Fixed condition to properly check if token is within refresh margin
Impact: Proper token caching and refresh behavior
Multiple Bug IDs Handling
Problem: State leakage between tests causing mock sequence mismatches
Solution: Implemented
resetServerState()
function for proper cleanupImpact: Consistent test results across multiple runs
Search Tools Implementation
Problem: Same state management issue affecting keyword search and other tools
Solution: Proper server state reset between tests
Impact: All 8 MCP tools now work correctly
Error Handling
Problem: API errors and network timeouts not properly converted to MCP error responses
Solution: Enhanced error handling in
handleMCPMessage()
functionImpact: Proper error responses for client applications
Authentication Failure Scenarios
Problem: Health endpoint returning 200 instead of 503 on auth failures
Solution: Module cache clearing and proper state isolation
Impact: Correct health status reporting
Test State Management
Problem: Module-level variables persisting between tests
Solution: Added
resetServerState()
export and proper module cache clearingImpact: True test isolation and reliable test results
Test Configuration
Jest: Using Jest with
--forceExit
flag for main test runsState Reset: Each test gets a fresh server instance with clean state
Mock Management: Proper fetch mocking with correct sequence handling
Test Isolation: Module cache clearing prevents state leakage
Key Implementation Details
Native fetch: Uses Node.js native fetch instead of external libraries
Token Management: 12-hour token validity with 30-minute refresh margin
Error Handling: Comprehensive error handling with proper MCP error responses
Security: Helmet security headers, CORS support, input validation
Logging: Structured JSON logging with timestamps
Development
Project Structure
Development Commands
Performance Considerations
Token caching reduces API calls
Pagination limits results to 10 per page
SSE heartbeat every 30 seconds keeps connections alive
Request timeout set to 30 seconds
Security Notes
Never commit
.env
file to version controlUse environment variables for all secrets
Review Cisco API usage limits and terms
Monitor logs for suspicious activity
API Reference
Authentication
OAuth2 URL:
https://id.cisco.com/oauth2/default/v1/token
Grant Type:
client_credentials
Token Validity: 12 hours
Auto-refresh: 30 minutes before expiry
Bug API Base URL
Base URL:
https://apix.cisco.com/bug/v2.0
MCP Protocol
The server implements the Model Context Protocol with these methods:
initialize
: Initialize MCP connectiontools/list
: List available toolstools/call
: Execute a tool
Example MCP message:
Health Monitoring
The server provides a comprehensive health check endpoint:
Response includes server status, OAuth2 token status, memory usage, uptime, and active connections.
Testing
Comprehensive Jest-based testing framework with:
✅ 33/33 tools tested - All MCP tools across 6 APIs
✅ Mock & Real API testing - Unit tests with mocks + integration tests with live APIs
✅ Individual tool testing - Standalone test runner for development
See 🧪 Testing Framework for complete testing documentation.
License
MIT License - see LICENSE file for details.
Contributing
Fork the repository
Create a feature branch
Make your changes
Add tests for new functionality
Ensure all tests pass:
npm test
Submit a pull request
Support
Resources
📖 Complete Documentation - Comprehensive project documentation
📚 Wiki - Detailed guides and troubleshooting
🐛 Issues - Report bugs and request features
External Resources
🔧 Cisco Developer Documentation - Official API documentation
🔒 Cisco PSIRT Documentation - Security vulnerability API documentation
💬 Cisco Services Discussions - Community support and API discussions
🌐 MCP Protocol - Model Context Protocol specification
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
A production-ready TypeScript MCP (Model Context Protocol) server for Cisco Support APIs with comprehensive security and dual transport support. This extensible server provides access to multiple Cisco Support APIs including Bug Search, Case Management, and End-of-Life information.
- 🚀 Current Features
- 📊 Supported Cisco APIs
- Quick Start
- Claude Desktop Integration
- MCP Prompts
- Screenshots
- 🔐 Security
- Configuration
- API Endpoints
- 📚 Documentation
- Usage Examples
- Health Monitoring
- Security Features
- Troubleshooting
- Testing
- Recent Test Fixes
- Development
- API Reference
- Health Monitoring
- Testing
- License
- Contributing
- Support
Related MCP Servers
- AsecurityFlicenseAqualityA template for creating Model Context Protocol (MCP) servers in TypeScript, offering features like container-based dependency injection, a service-based architecture, and integration with the LLM CLI for architectural design feedback through natural language.Last updated -127
- AsecurityAlicenseAqualityA simple TypeScript library for creating Model Context Protocol (MCP) servers with features like type safety, parameter validation, and a minimal code API.Last updated -101MIT License
- -securityFlicense-qualityA template repository for building Model Context Protocol (MCP) servers with TypeScript, featuring full TypeScript support, testing setup, CI/CD pipelines, and modular architecture for easy extension.Last updated -0
- -securityFlicense-qualityA comprehensive Model Context Protocol (MCP) server that provides 37+ intelligent development tools across JavaScript/TypeScript, Rust, and Python with security-first design and high-performance features.Last updated -111