CiscoSecureNetworkAnalytics-MCPServer

Cisco Secure Network Analytics MCP Server

MCP server for integrating Cisco Secure Network Analytics (SNA) with AI assistants and other Model Context Protocol (MCP) clients.

The server provides structured access to network telemetry and security information from Cisco SNA through MCP tools. It is designed to make network-flow and security-event data available to AI systems without exposing the underlying SNA API directly to the MCP client.

Status: Active development Protocol: Model Context Protocol (MCP) Backend: Cisco Secure Network Analytics (SNA)

---

Features

• 🔎 Query network flows for a specific host
• 🛡️ Query security events from Cisco SNA
• 🤖 Expose SNA functionality through the Model Context Protocol
• 🐳 Docker / Podman deployment support
• 🔐 Configuration through environment variables
• 🧪 Automated unit tests with coverage
• 🔍 Static code analysis with Ruff, Pylint and MyPy
• 🛡️ Security analysis with Bandit and GitHub CodeQL
• 📦 Automated Docker image publishing to GitHub Container Registry
• 🔄 Dependency monitoring with Dependabot

---

Architecture

The MCP server acts as an interface between an MCP client and Cisco Secure Network Analytics:

┌─────────────────────┐
│     MCP Client      │
│                     │
│ OpenWebUI / AI      │
│ Assistant / Client  │
└──────────┬──────────┘
           │
           │ Model Context Protocol
           ▼
┌─────────────────────┐
│   MCP Server        │
│                     │
│ FastMCP / Python    │
│                     │
│ - Flow queries      │
│ - Security events   │
│ - Asset queries     │
└──────────┬──────────┘
           │
           │ SNA API
           ▼
┌─────────────────────┐
│ Cisco Secure        │
│ Network Analytics   │
└─────────────────────┘

---

Requirements

Local development

• Python 3.12 or newer
• Access to a Cisco Secure Network Analytics instance
• SNA API credentials
• Git

Container deployment

One of:

• Docker
• Podman

A container runtime with access to the SNA API is required.

---

Installation

For initial deployment, it is recommended to use a local test environment before deploying the MCP server into a production network.

Test the available endpoints and MCP tools first. Once the deployment has been validated, the application can be deployed using Docker or Podman.

1. Clone the repository

git clone https://github.com/LennartVolz/CiscoSecureNetworkAnalytics_MCPServer.git
cd CiscoSecureNetworkAnalytics_MCPServer

2. Create a virtual environment

python3 -m venv venv
source venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Configure the environment

Create a local .env file based on the provided example:

cp .env.example .env

Edit .env and provide the required Cisco SNA configuration.

Never commit the .env file or real credentials to Git.

---

Running locally

Start the MCP server with:

python -m src.mcp_server

The server is expected to listen on:

http://127.0.0.1:8000

The MCP endpoint is:

http://127.0.0.1:8000/mcp

---

Docker / Podman

The repository contains a compatible Compose configuration for containerized deployment.

Configure credentials

cp .env.example .env

Edit .env and configure the Cisco SNA credentials.

Build and start the server

docker compose up --build -d

For subsequent starts, rebuilding is normally unnecessary:

docker compose up -d

View logs

docker compose logs -f

To stop the deployment:

docker compose down

The same Compose configuration can generally be used with Podman Compose.

Security: Do not expose the MCP endpoint to untrusted networks without appropriate authentication, network restrictions and access controls.

---

MCP Usage

The MCP server exposes its functionality through the /mcp endpoint.

The following examples use curl and are intended primarily for troubleshooting and local testing.

Initialize an MCP session

curl -i \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -X POST http://127.0.0.1:8000/mcp \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "capabilities": {},
      "clientInfo": {
        "name": "curl-test",
        "version": "1.0"
      }
    }
  }'

The response contains an Mcp-Session-Id.

Save this session ID for subsequent requests.

---

List available tools

Replace <SESSION_ID> with the session ID returned during initialization:

curl \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: <SESSION_ID>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }' \
  http://127.0.0.1:8000/mcp

This returns the tools currently exposed by the MCP server.

---

Query network flows

The get_flows tool can be used to retrieve network-flow information for a host.

curl -i \
  -H "Accept: application/json, text/event-stream" \
  -H "Content-Type: application/json" \
  -H "Mcp-Session-Id: <SESSION_ID>" \
  -X POST http://127.0.0.1:8000/mcp \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_flows",
      "arguments": {
        "subject_ip": "192.0.2.10",
        "minutes": 60,
        "record_limit": 100
      }
    }
  }'

Replace 192.0.2.10 with the IP address of the host you want to investigate.

---

Query security events

The get_security_events tool retrieves security events associated with a host.

curl -N \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Mcp-Session-Id: <SESSION_ID>" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "get_security_events",
      "arguments": {
        "subject_ip": "192.0.2.10",
        "minutes": 60
      }
    }
  }' \
  http://127.0.0.1:8000/mcp

---

Testing

The project uses Python's built-in unittest framework.

Run the complete test suite:

python -m unittest discover -s tests -v

Run the tests with coverage:

coverage run -m unittest discover -s tests -v
coverage report

The CI pipeline currently requires a minimum coverage of 80%.

---

Code Quality & Security

The project uses several automated checks through GitHub Actions.

Check	Purpose
Ruff	Linting and code-quality checks
Pylint	Static code analysis
MyPy	Static type checking
Bandit	Python security analysis
CodeQL	Security vulnerability analysis
Unit Tests	Automated functional testing
Dependabot	Dependency monitoring

GitHub Actions

---

Security

This project processes potentially security-sensitive network telemetry from Cisco Secure Network Analytics.

Please review SECURITY.md before deploying the application.

In particular:

• Never commit SNA credentials or API tokens.
• Keep .env files out of version control.
• Enable TLS certificate verification in production.
• Restrict access to the MCP endpoint.
• Do not expose the MCP server directly to untrusted networks.
• Avoid logging credentials, tokens or session identifiers.
• Keep dependencies and the Docker base image up to date.

---

Configuration

Configuration is provided through environment variables.

Use .env.example as the reference for the required variables:

cp .env.example .env

The actual .env file is intended for local or deployment-specific configuration and must not be committed to Git.

---

Deployment Recommendations

For production deployments, the following architecture is recommended:

                    ┌──────────────────┐
                    │   MCP Client     │
                    └────────┬─────────┘
                             │
                             │ Restricted access
                             ▼
                    ┌──────────────────┐
                    │ Reverse Proxy /  │
                    │ Access Control   │
                    └────────┬─────────┘
                             │
                             ▼
                    ┌──────────────────┐
                    │   MCP Server     │
                    │ Docker / Podman  │
                    └────────┬─────────┘
                             │
                             │ TLS
                             ▼
                    ┌──────────────────┐
                    │ Cisco Secure     │
                    │ Network Analytics│
                    └──────────────────┘

The MCP server should only be reachable by trusted MCP clients.

---

Development

Contributions and improvements are welcome.

Current development areas include:

• Custom exception classes for flow queries
• Additional SNA API integrations
• Improved error handling
• Additional unit-test coverage
• Additional MCP tools
• Improved data aggregation for AI consumption
• Additional security hardening
• Improved documentation

If you want to contribute, please create a feature branch and submit a pull request.

---

License

This project is licensed under the Apache License 2.0.

Copyright © 2026 Lennart Volz. All rights reserved.

---

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Cisco Systems, Inc.

Cisco and Cisco Secure Network Analytics are trademarks or registered trademarks of Cisco Systems, Inc. and/or its affiliates.