Google Threat Intelligence Server

This is a standalone MCP (Model Context Protocol) server for interacting with Google's Threat Intelligence suite. It provides AI assistants like Claude with access to comprehensive threat intelligence capabilities through both local development and production cloud deployment modes.

Key Capabilities:

• 🔍 Threat intelligence search (campaigns, threat actors, malware families)
• 📁 File analysis and behavior reports
• 🌐 Domain, IP, and URL reputation checking
• 🎯 IOC (Indicator of Compromise) search
• 📊 Threat profiles and hunting rulesets

Learn more about MCP

Architecture

Understanding how GTI MCP Server works in different deployment modes:

Component Overview

graph TB
    subgraph "MCP Clients"
        A1[Claude Desktop]
        A2[Cline]
        A3[Cursor]
        A4[Custom Frontend]
    end

    subgraph "Transport Layer"
        B1[stdio - Local]
        B2[SSE/HTTP - Remote]
    end

    subgraph "GTI MCP Server"
        C1[MCP Tools]
        C2[VT API Client]
    end

    D[VirusTotal/GTI API]

    A1 --> B1
    A2 --> B1
    A3 --> B1
    A4 --> B2

    B1 --> C1
    B2 --> C1

    C1 --> C2
    C2 --> D

    style C1 fill:#e1f5ff
    style C2 fill:#e1f5ff

Local Deployment Flow

For individual developers running the MCP server locally:

sequenceDiagram
    participant Client as MCP Client
    participant Server as GTI MCP Server
    participant Env as Environment
    participant VT as VirusTotal API

    Client->>Server: Launch via stdio
    Server->>Env: Read VT_APIKEY
    Env-->>Server: API Key
    Client->>Server: Call tool (e.g., get_file_report)
    Server->>VT: API Request with VT_APIKEY
    VT-->>Server: Response
    Server-->>Client: Tool Result

API Key Management: Server reads VT_APIKEY from environment variables at startup.

Cloud Deployment Flow

For teams deploying a centralized service:

sequenceDiagram
    participant Frontend as Frontend Client
    participant CloudRun as Cloud Run (SSE)
    participant Auth as Auth Middleware
    participant Server as GTI MCP Server
    participant VT as VirusTotal API

    Frontend->>CloudRun: Connect to /sse endpoint
    CloudRun->>Auth: Validate X-Mcp-Authorization header
    Auth-->>CloudRun: Authorized
    CloudRun-->>Frontend: SSE Connection Established

    Frontend->>CloudRun: Call tool with api_key parameter
    CloudRun->>Server: Execute tool
    Server->>VT: API Request with client-provided api_key
    VT-->>Server: Response
    Server-->>CloudRun: Tool Result
    CloudRun-->>Frontend: SSE Event with Result

API Key Management: Clients pass api_key parameter with each tool call. Server authenticates connection via MCP_AUTH_TOKEN but uses client-provided API keys for VirusTotal requests.

Security Note: This architecture allows teams to deploy a shared MCP server while maintaining individual user API quotas and access controls.

Features

Collections (Threats)

• get_collection_report(id): Retrieves a specific collection report by its ID (e.g., report--<hash>, threat-actor--<hash>).
• get_entities_related_to_a_collection(id, relationship_name, limit=10): Gets related entities (domains, files, IPs, URLs, other collections) for a given collection ID.
• get_collection_timeline_events(id): Retrieves curated timeline events for a collection.
• get_collection_rules(id): Gets detection rules (YARA and Sigma) associated with a collection.
• get_collection_feature_matches(id): Retrieves feature matches for a collection.
• get_collection_mitre_tree(id): Gets the MITRE ATT&CK framework tree for a collection.
• get_collections_commonalities(ids): Finds commonalities between multiple collections.
• create_collection(name, description): Creates a new threat collection.
• update_collection_attributes(id, attributes): Updates metadata and attributes for a collection.
• update_iocs_in_collection(id, iocs): Updates indicators of compromise in a collection.
• search_threats(query, limit=5, order_by="relevance-"): Performs a general search for threats (collections) using GTI query syntax.
• search_campaigns(query, limit=10, order_by="relevance-"): Searches specifically for collections of type campaign.
• search_threat_actors(query, limit=10, order_by="relevance-"): Searches specifically for collections of type threat-actor.
• search_malware_families(query, limit=10, order_by="relevance-"): Searches specifically for collections of type malware-family.
• search_software_toolkits(query, limit=10, order_by="relevance-"): Searches specifically for collections of type software-toolkit.
• search_threat_reports(query, limit=10, order_by="relevance-"): Searches specifically for collections of type report.
• search_vulnerabilities(query, limit=10, order_by="relevance-"): Searches specifically for collections of type vulnerability.

Files

• get_file_report(hash): Retrieves a comprehensive analysis report for a file based on its MD5, SHA1, or SHA256 hash.
• get_entities_related_to_a_file(hash, relationship_name, limit=10): Gets related entities (domains, IPs, URLs, behaviours, etc.) for a given file hash.
• get_file_behavior_report(file_behaviour_id): Retrieves a specific sandbox behavior report for a file.
• get_file_behavior_summary(hash): Retrieves a summary of all sandbox behavior reports for a file hash.
• analyse_file(file_path): Uploads and analyzes a file, returning a comprehensive threat intelligence report.

Intelligence Search

• search_iocs(query, limit=10, order_by="last_submission_date-"): Searches for Indicators of Compromise (files, URLs, domains, IPs) using advanced GTI query syntax.
• search_digital_threat_monitoring(query, limit=10): Searches digital threat monitoring data for brand protection, phishing, and impersonation threats.

Network Locations (Domains & IPs)

• get_domain_report(domain): Retrieves a comprehensive analysis report for a domain.
• get_entities_related_to_a_domain(domain, relationship_name, limit=10): Gets related entities for a given domain.
• get_ip_address_report(ip_address): Retrieves a comprehensive analysis report for an IPv4 or IPv6 address.
• get_entities_related_to_an_ip_address(ip_address, relationship_name, limit=10): Gets related entities for a given IP address.

URLs

• get_url_report(url): Retrieves a comprehensive analysis report for a URL.
• get_entities_related_to_an_url(url, relationship_name, limit=10): Gets related entities for a given URL.

Hunting

• get_hunting_ruleset: Get a Hunting Ruleset object from Google Threat Intelligence.
• get_entities_related_to_a_hunting_ruleset: Retrieve entities related to the given Hunting Ruleset.

Threat Profiles

• list_threat_profiles: List your Threat Profiles at Google Threat Intelligence.
• get_threat_profile(profile_id): Get Threat Profile object.
• get_threat_profile_recommendations(profile_id, limit=10): Returns the list of objects associated to the given Threat Profile.
• get_threat_profile_associations_timeline(profile_id): Retrieves the associations timeline for the given Threat Profile.

Quick Start (Local Development)

For developers who want to use GTI MCP Server with Claude Desktop, Cline, Cursor, or other MCP clients.

Prerequisites

• Python 3.11 or higher
• uv package manager
• VirusTotal API key (get one free)

Installation

# Clone the repository
git clone https://github.com/googleSandy/gti-mcp-standalone.git
cd gti-mcp-standalone

# Install with uv (recommended)
uv tool install -e .

# Or run directly without installation
uv run gti_mcp

API Key Setup

Set up the VT_APIKEY environment variable:

macOS/Linux:

export VT_APIKEY="your-virustotal-api-key"

Windows PowerShell:

$Env:VT_APIKEY = "your-virustotal-api-key"

Permanent setup (recommended):

Add the export command to your shell profile (~/.bashrc, ~/.zshrc, or ~/.bash_profile):

echo 'export VT_APIKEY="your-virustotal-api-key"' >> ~/.zshrc
source ~/.zshrc

MCP Client Configuration

Claude Desktop

Edit ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gti": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/gti-mcp-standalone",
        "run",
        "gti_mcp"
      ],
      "env": {
        "VT_APIKEY": "${VT_APIKEY}"
      }
    }
  }
}

Note for macOS users: If you installed uv using the standalone installer, use the full path to the uv binary (e.g., /Users/yourusername/.local/bin/uv) instead of just uv.

Cline

Edit .cline/mcp.json or use the settings UI:

{
  "mcpServers": {
    "gti": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/gti-mcp-standalone",
        "run",
        "gti_mcp"
      ],
      "env": {
        "VT_APIKEY": "${VT_APIKEY}"
      }
    }
  }
}

Cursor

Edit .cursor/mcp.json:

{
  "mcpServers": {
    "gti": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/gti-mcp-standalone",
        "run",
        "gti_mcp"
      ],
      "env": {
        "VT_APIKEY": "${VT_APIKEY}"
      }
    }
  }
}

Verification

1. Restart your MCP client (Claude Desktop, Cline, or Cursor)
2. Check that the GTI server appears in the MCP tools list
3. Try a simple query: "Check the reputation of google.com using GTI"

If everything is working, you should see results from Google Threat Intelligence!

Production Deployment (Cloud Run)

For teams who want to deploy a centralized GTI MCP service that multiple users or frontend applications can access via SSE (Server-Sent Events).

Why Cloud Deployment?

• Centralized service: One deployment serves multiple users/applications
• No local setup: Users connect via HTTP/SSE without installing Python or dependencies
• Team sharing: Security teams can provide threat intelligence to multiple frontend apps
• Scalability: Cloud Run automatically scales based on demand

Prerequisites

• Google Cloud Platform account with billing enabled
• gcloud CLI installed and configured
• Project with Cloud Run API enabled

Deployment Steps

1. Clone the Repository

git clone https://github.com/googleSandy/gti-mcp-standalone.git
cd gti-mcp-standalone

2. Configure Deployment Script

Edit gti-remotemcp-deploy.sh and update the configuration section:

# Edit these three values:
PROJECT_ID="your-gcp-project-id"        # Find at console.cloud.google.com
SERVICE_NAME="gti-remotemcp-server"     # Name for your Cloud Run service
REGION="us-central1"                     # Your preferred region

3. Run Deployment

chmod +x gti-remotemcp-deploy.sh
./gti-remotemcp-deploy.sh

The script will:

• Build the container using Google Cloud Buildpacks
• Deploy to Cloud Run
• Output the service URL and authentication token

4. Save Deployment Information

The script outputs:

• Service URL: https://gti-remotemcp-server-xyz.a.run.app
• SSE Endpoint: https://gti-remotemcp-server-xyz.a.run.app/sse
• Auth Token: A randomly generated token for authentication

Important: Save the auth token securely! You'll need it to connect clients.

Architecture Details

Transport: SSE (Server-Sent Events) over HTTP

Authentication:

• Server access: X-Mcp-Authorization header with MCP_AUTH_TOKEN
• API calls: api_key parameter passed with each tool invocation

API Key Strategy:

• Server does NOT store VirusTotal API keys
• Each tool call must include api_key parameter
• Allows per-user API quotas and access control
• Client applications manage API key distribution

Security Considerations

1. Protect the auth token: Store MCP_AUTH_TOKEN securely (environment variables, secrets manager)
2. HTTPS only: Cloud Run enforces HTTPS by default
3. API key handling: Client applications should never expose VT API keys in frontend code
4. Access control: Consider adding additional authentication layers for production use
5. Rate limiting: VirusTotal enforces rate limits per API key

Frontend Integration

For developers building custom frontend applications that connect to the deployed Cloud Run service.

Connection Overview

• Protocol: SSE (Server-Sent Events) for events, HTTP POST for JSON-RPC messages
• Transport: @modelcontextprotocol/sdk/client/sse
• Authentication: Bearer-style token in X-Mcp-Authorization header
• API Keys: Pass api_key parameter with each tool call

Configuration Parameters

1. Service URL: Your Cloud Run service URL + /sse
   • Example: https://gti-remotemcp-server-xyz.a.run.app/sse
2. Auth Token: The MCP_AUTH_TOKEN from deployment output
3. VT API Key: VirusTotal API key (managed client-side, passed per tool call)

React/TypeScript Example

Complete implementation using the MCP SDK:

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";

// Configuration (use environment variables in production)
const MCP_SERVER_URL = process.env.REACT_APP_MCP_SERVER_URL || "https://your-service.a.run.app/sse";
const MCP_AUTH_TOKEN = process.env.REACT_APP_MCP_AUTH_TOKEN || "your-auth-token";
const VT_API_KEY = process.env.REACT_APP_VT_API_KEY || "your-vt-api-key";

// Create SSE transport with authentication
const transport = new SSEClientTransport(
  new URL(MCP_SERVER_URL),
  {
    // Headers for SSE connection (GET request)
    eventSourceInit: {
      headers: {
        "X-Mcp-Authorization": MCP_AUTH_TOKEN,
      }
    },
    // Headers for JSON-RPC messages (POST requests)
    requestInit: {
      headers: {
        "X-Mcp-Authorization": MCP_AUTH_TOKEN,
      }
    }
  }
);

// Create MCP client
const client = new Client(
  {
    name: "gti-frontend-client",
    version: "1.0.0",
  },
  {
    capabilities: {
      tools: {},
      resources: {},
    },
  }
);

// Connect to server
async function connectToGTI() {
  try {
    await client.connect(transport);
    console.log("✅ Connected to GTI MCP Server");
    return true;
  } catch (error) {
    console.error("❌ Connection failed:", error);
    return false;
  }
}

// Example: Call a tool
async function checkFileReputation(fileHash: string) {
  try {
    const result = await client.callTool({
      name: "get_file_report",
      arguments: {
        hash: fileHash,
        api_key: VT_API_KEY  // ⚠️ Required: Pass API key with each call
      }
    });

    console.log("File report:", result);
    return result;
  } catch (error) {
    console.error("Tool call failed:", error);
    throw error;
  }
}

// Example: Search for threats
async function searchThreats(query: string) {
  try {
    const result = await client.callTool({
      name: "search_threats",
      arguments: {
        query: query,
        limit: 10,
        api_key: VT_API_KEY  // ⚠️ Required: Pass API key with each call
      }
    });

    console.log("Threat search results:", result);
    return result;
  } catch (error) {
    console.error("Search failed:", error);
    throw error;
  }
}

// Initialize
connectToGTI().then(success => {
  if (success) {
    // Example usage
    checkFileReputation("44d88612fea8a8f36de82e1278abb02f");
    searchThreats("APT28");
  }
});

Important: API Key Handling

Every tool call MUST include the api_key parameter:

const result = await client.callTool({
  name: "any_gti_tool",
  arguments: {
    // ... other tool-specific arguments ...
    api_key: VT_API_KEY  // ⚠️ Always required
  }
});

Why? The Cloud Run deployment does not store API keys. This allows:

• Per-user API quotas
• Individual access control
• Secure key management on client side

Security Best Practices:

• Never hardcode API keys in frontend code
• Use environment variables or secure configuration
• Consider backend proxy for additional security
• Implement proper key rotation policies

CORS Considerations

The server allows cross-origin requests by passing OPTIONS requests through authentication middleware. If you encounter CORS issues:

1. Verify your request includes the X-Mcp-Authorization header
2. Check browser console for specific CORS errors
3. Ensure you're using HTTPS for the Cloud Run URL
4. Consider adding Starlette's CORSMiddleware if strict CORS enforcement is needed

Troubleshooting

Connection fails:

• Verify service URL is correct (must end with /sse)
• Check MCP_AUTH_TOKEN matches deployment output
• Ensure Cloud Run service is running (gcloud run services list)

Tool calls fail:

• Verify api_key parameter is included in arguments
• Check VirusTotal API key is valid
• Review rate limits on your VirusTotal account

Authentication errors:

• Confirm X-Mcp-Authorization header is set correctly
• Check token hasn't been regenerated during redeployment

Development

Project Structure

.
├── gti_mcp/
│   ├── __init__.py
│   ├── server.py           # Main MCP server implementation
│   ├── utils.py            # VirusTotal API utilities
│   └── tools/              # Tool implementations
│       ├── __init__.py
│       ├── collections.py  # Threat collections tools
│       ├── files.py        # File analysis tools
│       ├── intelligence.py # IOC search tools
│       ├── netloc.py       # Domain/IP tools
│       ├── threat_profiles.py
│       └── urls.py         # URL analysis tools
├── tests/                  # Test suite
│   ├── conftest.py
│   ├── test_tools.py
│   ├── test_utils.py
│   └── test_files_errors.py
├── pyproject.toml          # Package configuration
├── Dockerfile              # Cloud Run container
├── gti-remotemcp-deploy.sh # Deployment script
└── README.md

Running Tests

# Install test dependencies
uv pip install -e ".[test]"

# Run all tests
pytest

# Run with coverage
pytest --cov=gti_mcp

# Run specific test file
pytest tests/test_tools.py -v

# Run specific test
pytest tests/test_tools.py::test_get_file_report -v

Contributing

To modify or extend this server:

1. Fork and clone the repository
2. Create a feature branch: git checkout -b feature/your-feature
3. Make changes in gti_mcp/tools/ following existing patterns
4. Add tests in tests/ for new functionality
5. Run tests to verify: pytest
6. Update README if adding new features or changing APIs
7. Commit changes: Use clear, descriptive commit messages
8. Push and create PR to the original repository

Adding New Tools

Example pattern for adding a new tool:

# In gti_mcp/tools/your_category.py

async def your_new_tool(param1: str, api_key: str) -> dict:
    """
    Tool description for MCP clients.

    Args:
        param1: Description of parameter
        api_key: VirusTotal API key (required for cloud deployment)

    Returns:
        Tool result as dictionary
    """
    import vt

    async with vt.Client(api_key) as client:
        result = await client.your_operation(param1)
        return result.to_dict()

# Register in gti_mcp/tools/__init__.py

License & Attribution

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Original Source

This is a standalone extraction of the Google Threat Intelligence MCP server from the official mcp-security repository.

Original Authors: Google SecOps Team Original Repository: https://github.com/google/mcp-security Original License: Apache 2.0

This standalone version is maintained independently but retains all original licensing and attribution.

Third-Party Libraries

• mcp - Model Context Protocol SDK (MIT License)
• vt-py - VirusTotal Python SDK (Apache 2.0)
• Starlette - ASGI framework (BSD License)
• uvicorn - ASGI server (BSD License)

Support

Getting Help

• Documentation: This README and MCP Protocol Docs
• Issues: Report issues at the original mcp-security repository
• VirusTotal API: Official API documentation

Frequently Asked Questions

Q: Do I need a paid VirusTotal account? A: No, a free VirusTotal account works. Note that free accounts have lower rate limits and not all MCP tools and features will work even though they will show as available.

Q: Can I use this with OpenAI or other LLM providers? A: Yes! This is an MCP server. Any MCP-compatible client can use it, not just Claude.

Q: Is my API key secure in cloud deployment? A: The server never stores API keys. Clients pass them per-call, allowing you to implement your own key management strategy.

Q: Can I deploy to platforms other than Cloud Run? A: Yes! The included Dockerfile works with any container platform (AWS ECS, Azure Container Instances, etc.). Cloud Run is just the default.

Q: What's the difference between this and the original mcp-security repo? A: This is a standalone extraction of just the GTI component, making it easier to deploy independently. The original repo contains multiple security tools.

---

Built with ❤️ using Model Context Protocol