# Google Threat Intelligence MCP Server (Standalone)

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.

![GTI MCP Server Screenshot](images/gti-mcp-screenshot.png)

**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](https://modelcontextprotocol.io/introduction)

## Architecture

Understanding how GTI MCP Server works in different deployment modes:

### Component Overview

```mermaid
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:

```mermaid
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:

```mermaid
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](https://docs.astral.sh/uv/) package manager
- VirusTotal API key ([get one free](https://www.virustotal.com/))

### Installation

```bash
# 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:**
```bash
export VT_APIKEY="your-virustotal-api-key"
```

**Windows PowerShell:**
```powershell
$Env:VT_APIKEY = "your-virustotal-api-key"
```

**Permanent setup (recommended):**

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

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

### MCP Client Configuration

#### Claude Desktop

Edit `~/.claude/claude_desktop_config.json`:

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

```json
{
  "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`:

```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](https://cloud.google.com/sdk/docs/install) installed and configured
- Project with Cloud Run API enabled

### Deployment Steps

#### 1. Clone the Repository

```bash
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:

```bash
# 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

```bash
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:

```typescript
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:**

```typescript
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

```bash
# 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:

```python
# 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](LICENSE) file for details.

### Original Source

This is a standalone extraction of the Google Threat Intelligence MCP server from the official [mcp-security](https://github.com/google/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](https://github.com/modelcontextprotocol/python-sdk) - Model Context Protocol SDK (MIT License)
- [vt-py](https://github.com/VirusTotal/vt-py) - VirusTotal Python SDK (Apache 2.0)
- [Starlette](https://www.starlette.io/) - ASGI framework (BSD License)
- [uvicorn](https://www.uvicorn.org/) - ASGI server (BSD License)

## Support

### Getting Help

- **Documentation:** This README and [MCP Protocol Docs](https://modelcontextprotocol.io/introduction)
- **Issues:** Report issues at the [original mcp-security repository](https://github.com/google/mcp-security/issues)
- **VirusTotal API:** [Official API documentation](https://developers.virustotal.com/reference/overview)

### 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](https://modelcontextprotocol.io/)**