Skip to main content
Glama

mcp-cisco-support

by sieteunoseis
npmGitHub
TypeScript
MIT License
80
5
  • Apple
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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

APIStatusToolsDescription
Enhanced Analysis (enhanced_analysis)⭐ RECOMMENDED6 toolsAdvanced analysis tools for comprehensive product assessment
Bug (bug)✅ Complete14 toolsBug Search, Details, Product-specific searches + Enhanced tools
Case (case)✅ Complete4 toolsSupport case management and operations
EoX (eox)✅ Complete4 toolsEnd of Life/Sale information and lifecycle planning
PSIRT (psirt)✅ Complete8 toolsProduct Security Incident Response Team vulnerability data
Product (product)✅ Complete3 toolsProduct details, specifications, and technical information
Software (software)✅ Complete6 toolsSoftware suggestions, releases, and upgrade recommendations
Serial (serial)🔄 Planned0 toolsSerial number to product information mapping
RMA (rma)🔄 Planned0 toolsReturn 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 users
  • SUPPORT_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

Start in stdio mode for Claude Desktop:

npx mcp-cisco-support

Start HTTP server with authentication:

npx mcp-cisco-support --http # Token displayed in console for authentication

Generate Bearer token for HTTP mode:

npx mcp-cisco-support --generate-token

Get help and see all options:

npx mcp-cisco-support --help

Environment Setup

  1. Generate authentication token (for HTTP mode):
    npx mcp-cisco-support --generate-token export MCP_BEARER_TOKEN=<generated_token>
  2. 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)
  3. Start the server:
    # For Claude Desktop (stdio mode) npx mcp-cisco-support # For HTTP access (with authentication) npx mcp-cisco-support --http

Local Development

git clone https://github.com/sieteunoseis/mcp-cisco-support.git cd mcp-cisco-support npm install npm run build npm start

Claude Desktop Integration

Prerequisites

  1. 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
  2. Install Claude Desktop:
    • Download from Claude.ai
    • Make sure you're using a recent version that supports MCP

Step-by-Step Setup

  1. Locate Claude Desktop Config File:
    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
  2. 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
  3. Replace Your Credentials:
    • Replace your_client_id_here with your actual Cisco Client ID
    • Replace your_client_secret_here with your actual Cisco Client Secret
  4. 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:

  1. Ask Claude about Cisco bugs:
    "Search for bugs related to memory leaks in Cisco switches"
  2. Get specific bug details:
    "Get details for Cisco bug CSCab12345"
  3. 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 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 Integration

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:

npm install -g mcp-cisco-support

Then use this config:

{ "mcpServers": { "cisco-support": { "command": "mcp-cisco-support", "env": { "CISCO_CLIENT_ID": "your_client_id_here", "CISCO_CLIENT_SECRET": "your_client_secret_here", "SUPPORT_API": "bug" } } } }
Local Installation

For development or custom setups:

git clone https://github.com/sieteunoseis/mcp-cisco-support.git cd mcp-cisco-support npm install npm run build

Then use this config:

{ "mcpServers": { "cisco-support": { "command": "node", "args": ["/path/to/mcp-cisco-support/dist/index.js"], "env": { "CISCO_CLIENT_ID": "your_client_id_here", "CISCO_CLIENT_SECRET": "your_client_secret_here", "SUPPORT_API": "bug" } } } }

Troubleshooting

Common Issues
  1. "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
  2. 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
  3. MCP server not loading:
    • Restart Claude Desktop completely
    • Check the config file syntax with a JSON validator
    • Look for Claude Desktop logs/error messages
  4. Permission errors:
    • Ensure the config file is readable
    • On macOS/Linux, check file permissions: chmod 644 claude_desktop_config.json
Debugging
  1. Test the server manually:
    npx mcp-cisco-support
    This should start the server in stdio mode without errors.
  2. Validate your config: Use a JSON validator to ensure your config file is properly formatted.
  3. 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*.log

    On Windows:

    # Check logs directory %APPDATA%\Claude\logs\
Getting Help

Docker Deployment

# Use pre-built image docker pull ghcr.io/sieteunoseis/mcp-cisco-support:latest docker run -p 3000:3000 \ -e CISCO_CLIENT_ID=your_id \ -e CISCO_CLIENT_SECRET=your_secret \ -e SUPPORT_API=bug \ ghcr.io/sieteunoseis/mcp-cisco-support:latest --http # Or build locally docker-compose up -d

🔐 Security

  • stdio mode: No authentication (Claude Desktop, local clients)
  • HTTP mode: Bearer token authentication required
# Generate secure token npx mcp-cisco-support --generate-token # Use token for HTTP mode export MCP_BEARER_TOKEN=your_token npx mcp-cisco-support --http

See 🔒 Security Guide for complete security documentation.

Configuration

Environment Variables

Create a .env file with your configuration:

# 🔑 Cisco API OAuth2 Configuration (REQUIRED) CISCO_CLIENT_ID=your_client_id_here CISCO_CLIENT_SECRET=your_client_secret_here # 🌐 Server Configuration PORT=3000 NODE_ENV=development # 🚀 API Support Configuration # Enable specific Cisco Support APIs you have access to # Options: bug, case, eox (plus planned: product, serial, rma, software, asd) SUPPORT_API=bug,case,eox # Multiple APIs # SUPPORT_API=all # All available APIs # SUPPORT_API=bug # Single API (default) # 🔐 HTTP Authentication Configuration (HTTP mode only) # Custom Bearer token for HTTP authentication (optional - generates random if not set) MCP_BEARER_TOKEN=your_custom_secure_token_here # ⚠️ SECURITY WARNING: Only use in development/testing # DANGEROUSLY_OMIT_AUTH=true # Disables HTTP authentication entirely

Claude Desktop Integration

Complete configuration for Claude Desktop:

{ "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,case,eox" } } } }

Docker Configuration

With authentication:

docker run -p 3000:3000 \ -e CISCO_CLIENT_ID=your_client_id \ -e CISCO_CLIENT_SECRET=your_client_secret \ -e SUPPORT_API=bug,case,eox \ -e MCP_BEARER_TOKEN=your_secure_token \ ghcr.io/sieteunoseis/mcp-cisco-support:latest --http

Without authentication (development only):

docker run -p 3000:3000 \ -e CISCO_CLIENT_ID=your_client_id \ -e CISCO_CLIENT_SECRET=your_client_secret \ -e DANGEROUSLY_OMIT_AUTH=true \ ghcr.io/sieteunoseis/mcp-cisco-support:latest --http

API Endpoints

EndpointMethodDescription
/GETServer information and available endpoints
/mcpPOSTMain MCP endpoint (JSON-RPC over HTTP)
/messagesPOSTAlternative MCP endpoint for N8N compatibility
/sseGETSSE connection with session management
/ssePOSTLegacy SSE message endpoint (deprecated)
/sse/session/{sessionId}POSTSession-specific MCP message endpoint
/pingGETSimple ping endpoint for connectivity testing
/healthGETHealth check with detailed status

📚 Documentation

For detailed information, see our comprehensive GitHub Wiki:

Usage Examples

cURL Examples

# Test server connectivity curl http://localhost:3000/ping # Check health status curl http://localhost:3000/health # List available tools (main MCP endpoint) curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": "1", "method": "tools/list" }' # List available tools (alternative endpoint for N8N) curl -X POST http://localhost:3000/messages \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": "1", "method": "tools/list" }' # Test SSE connection (will show endpoint event) curl -N http://localhost:3000/sse # Search for bugs by keyword curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": "2", "method": "tools/call", "params": { "name": "search_bugs_by_keyword", "arguments": { "keyword": "crash", "severity": "1", "status": "open" } } }' # Get specific bug details curl -X POST http://localhost:3000/mcp \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": "3", "method": "tools/call", "params": { "name": "get_bug_details", "arguments": { "bug_ids": "CSCab12345" } } }'

JavaScript Client Example

async function searchBugs(keyword) { const response = await fetch('http://localhost:3000/mcp', { method: 'POST', headers: { 'Content-Type': 'application/json', }, body: JSON.stringify({ jsonrpc: '2.0', id: Date.now(), method: 'tools/call', params: { name: 'search_bugs_by_keyword', arguments: { keyword: keyword, page_index: 1, status: 'open' } } }) }); const result = await response.json(); return result; }

Health Monitoring

The server provides a comprehensive health check endpoint:

curl http://localhost:3000/health

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

  1. OAuth2 Authentication Failed
    • Verify CISCO_CLIENT_ID and CISCO_CLIENT_SECRET
    • Check network connectivity to https://id.cisco.com
  2. API Calls Failing
    • Check token validity at /health
    • Verify network access to https://apix.cisco.com
  3. 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

# Run all tests npm test # Run tests in watch mode npm run test:watch # Run tests with coverage npm run test:coverage # Run specific test suite npx jest tests/auth.test.js npx jest tests/mcp-tools.test.js

Test Structure

The test suite includes:

  • Authentication Tests (tests/auth.test.js): OAuth2 authentication, token management, error handling
  • MCP Tools Tests (tests/mcp-tools.test.js): All 8 MCP tools, error handling, pagination
  • Setup (tests/setup.js): Test environment configuration

Recent Test Fixes

The following issues were identified and resolved in the test suite:

✅ Fixed Issues

  1. 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
  2. Multiple Bug IDs Handling
    • Problem: State leakage between tests causing mock sequence mismatches
    • Solution: Implemented resetServerState() function for proper cleanup
    • Impact: Consistent test results across multiple runs
  3. 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
  4. Error Handling
    • Problem: API errors and network timeouts not properly converted to MCP error responses
    • Solution: Enhanced error handling in handleMCPMessage() function
    • Impact: Proper error responses for client applications
  5. 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
  6. Test State Management
    • Problem: Module-level variables persisting between tests
    • Solution: Added resetServerState() export and proper module cache clearing
    • Impact: True test isolation and reliable test results

Test Configuration

  • Jest: Using Jest with --forceExit flag for main test runs
  • State 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

mcp-cisco-support/ ├── src/ │ └── index.ts # Main TypeScript server implementation ├── dist/ # Compiled JavaScript (generated by build) ├── package.json # Dependencies and scripts ├── tsconfig.json # TypeScript configuration ├── .env.example # Environment variables template ├── .env # Actual environment variables (create from example) ├── .gitignore # Git ignore rules ├── Dockerfile # Docker configuration ├── docker-compose.yml # Docker Compose setup ├── screenshots/ # Documentation screenshots │ └── mcp-inspector-screenshot.png ├── CLAUDE.md # Project instructions and architecture └── README.md # Project documentation

Development Commands

# Install dependencies npm install # Start development server with auto-reload npm run dev # Run tests npm test # Run tests in watch mode npm run test:watch # Build Docker image docker build -t mcp-cisco-support . # View logs in development npm run dev 2>&1 | jq '.' # Pretty print JSON logs

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 control
  • Use 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 connection
  • tools/list: List available tools
  • tools/call: Execute a tool

Example MCP message:

{ "jsonrpc": "2.0", "id": "1", "method": "tools/call", "params": { "name": "search_bugs_by_keyword", "arguments": { "keyword": "memory leak", "status": "open" } } }

Health Monitoring

The server provides a comprehensive health check endpoint:

curl http://localhost:3000/health

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
# Run all tests npm test # Test with real API credentials CISCO_CLIENT_ID=your_id CISCO_CLIENT_SECRET=your_secret npm test # Test individual tools npm run test:tool search_bugs_by_keyword

See 🧪 Testing Framework for complete testing documentation.

License

MIT License - see LICENSE file for details.

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests for new functionality
  5. Ensure all tests pass: npm test
  6. Submit a pull request

Support

Resources

External Resources

Deploy Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

View all 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.

  1. 🚀 Current Features
    1. 📊 Supported Cisco APIs
      1. Quick Start
        1. NPX Installation (Recommended)
        2. Environment Setup
        3. Local Development
      2. Claude Desktop Integration
        1. Prerequisites
        2. Step-by-Step Setup
        3. Verification
        4. Example Usage in Claude Desktop
      3. MCP Prompts
        1. Screenshots
          1. Claude Desktop Integration
          2. MCP Inspector
          3. Alternative Installation Methods
          4. Troubleshooting
          5. Docker Deployment
        2. 🔐 Security
          1. Configuration
            1. Environment Variables
            2. Claude Desktop Integration
            3. Docker Configuration
          2. API Endpoints
            1. 📚 Documentation
              1. Usage Examples
                1. cURL Examples
                2. JavaScript Client Example
              2. Health Monitoring
                1. Security Features
                  1. Troubleshooting
                    1. Common Issues
                    2. Logs
                  2. Testing
                    1. Running Tests
                    2. Test Structure
                  3. Recent Test Fixes
                    1. ✅ Fixed Issues
                    2. Test Configuration
                    3. Key Implementation Details
                  4. Development
                    1. Project Structure
                    2. Development Commands
                    3. Performance Considerations
                    4. Security Notes
                  5. API Reference
                    1. Authentication
                    2. Bug API Base URL
                    3. MCP Protocol
                  6. Health Monitoring
                    1. Testing
                      1. License
                        1. Contributing
                          1. Support
                            1. Resources
                            2. External Resources

                          Related MCP Servers

                          • MCP Server Template

                            stevennevins
                            A
                            security
                            F
                            license
                            A
                            quality
                            A 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 -
                            1
                            10
                            7

                          • MCPKit

                            ribeirogab
                            A
                            security
                            A
                            license
                            A
                            quality
                            A simple TypeScript library for creating Model Context Protocol (MCP) servers with features like type safety, parameter validation, and a minimal code API.
                            Last updated -
                            1
                            5
                            1
                            MIT License

                          • MCP TypeScript Server Template

                            Mearman
                            -
                            security
                            F
                            license
                            -
                            quality
                            A 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 -
                            3

                          • MOIDVK

                            moikas-code
                            -
                            security
                            F
                            license
                            -
                            quality
                            A 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 -
                            8
                            1

                          View all related MCP servers

                          New MCP Servers

                          MCP directory API

                          We provide all the information about MCP servers via our MCP API.

                          curl -X GET 'https://glama.ai/api/mcp/v1/servers/sieteunoseis/mcp-cisco-support'

                          If you have feedback or need assistance with the MCP directory API, please join our Discord server