davydany/mcp_taxii

MCP TAXII

A Model Context Protocol (MCP) server that acts as a TAXII client for AI agents, enabling them to interact with Threat Intelligence platforms using the TAXII protocol.

Overview

MCP TAXII provides a bridge between AI agents and TAXII (Trusted Automated eXchange of Intelligence Information) servers, allowing AI systems to:

• Query threat intelligence data
• Retrieve STIX objects from TAXII collections
• Discover available threat intelligence sources
• Add new threat intelligence to collections (when permitted)

The server supports both TAXII 2.0 and TAXII 2.1 protocols.

Features

• TAXII 2.0 & 2.1 Support: Compatible with both major TAXII protocol versions
• FastMCP Framework: Built on FastMCP for efficient MCP server implementation
• Authentication Support: Handles username/password authentication for TAXII servers
• Collection Management: Browse, query, and interact with TAXII collections
• STIX Object Operations: Retrieve and add STIX threat intelligence objects
• Pagination Support: Handles large datasets with built-in pagination (TAXII 2.1)
• Environment Variable Configuration: Easy setup via environment variables

Installation

Prerequisites

• Python 3.11 or higher
• uv package manager

Setup

1. Clone the repository:

git clone <repository-url>
cd mcp_taxii

2. Install dependencies using uv:

uv sync --extra dev

3. Configure environment variables (optional):

export TAXII_URL="https://your-taxii-server.com/taxii2/"
export TAXII_USERNAME="your-username"
export TAXII_PASSWORD="your-password"

Usage

Running the Server

uv run python -m mcp_taxii.server

Available Tools

The MCP TAXII server provides the following tools for AI agents:

initialize_taxii

Initialize connection to a TAXII server.

Parameters:

• url (optional): TAXII server URL
• username (optional): Authentication username
• password (optional): Authentication password
• version: TAXII version ("2.0" or "2.1", defaults to "2.1")

get_discovery

Retrieve TAXII server discovery information including available API roots.

get_collections

List available collections from the TAXII server.

Parameters:

• api_root (optional): Specific API root URL

get_collection_objects

Retrieve STIX objects from a specific collection.

Parameters:

• collection_id: ID of the collection to query
• api_root (optional): Specific API root URL
• limit: Maximum number of objects to retrieve (default: 100)
• added_after (optional): ISO timestamp to filter objects added after this time

get_object_manifest

Get object manifest (metadata) from a collection.

Parameters:

• collection_id: ID of the collection
• api_root (optional): Specific API root URL
• limit: Maximum number of manifest entries (default: 100)

add_objects

Add STIX objects to a writable collection.

Parameters:

• collection_id: ID of the target collection
• objects: List of STIX objects to add
• api_root (optional): Specific API root URL

Example Integration

Here's how an AI agent might interact with the MCP TAXII server:

# Initialize connection
await initialize_taxii(
    url="https://intel.example.com/taxii2/",
    username="analyst",
    password="secure_password",
    version="2.1"
)

# Discover available resources
discovery = await get_discovery()

# List collections
collections = await get_collections()

# Retrieve threat indicators
indicators = await get_collection_objects(
    collection_id="indicators-collection",
    limit=50
)

# Add new threat intelligence
new_indicators = [
    {
        "type": "indicator",
        "id": "indicator--" + str(uuid4()),
        "created": "2024-01-01T00:00:00.000Z",
        "modified": "2024-01-01T00:00:00.000Z",
        "pattern": "[file:hashes.MD5 = 'malicious_hash']",
        "valid_from": "2024-01-01T00:00:00.000Z"
    }
]
status = await add_objects("indicators-collection", new_indicators)

Development

Running Tests

uv run pytest

Code Formatting

uv run ruff format src/ tests/

Linting

uv run ruff check src/ tests/

Project Structure

mcp_taxii/
├── docs/                    # Documentation
├── aidocs/                  # AI-specific documentation
│   └── specs/              # TAXII specification docs
├── dev/                     # Development tools
│   └── taxii_test_server/  # Test TAXII server
├── src/
│   └── mcp_taxii/
│       ├── __init__.py
│       ├── server.py       # Main MCP server implementation
│       └── clients/        # TAXII client implementations
│           ├── base.py     # Abstract base client
│           ├── taxii_20.py # TAXII 2.0 client
│           └── taxii_21.py # TAXII 2.1 client
├── tests/                   # Test suite
│   ├── conftest.py         # Shared test fixtures
│   └── test_server.py      # Server tests
├── pyproject.toml          # Project configuration
├── CLAUDE.md               # AI agent instructions
└── README.md               # This file

Test Server

A compliant TAXII 2.0/2.1 test server is available in the dev/ directory for testing purposes. See for details.

License

[Specify your license here]

Contributing

[Add contribution guidelines if applicable]