# Google Threat Intelligence (GTI) MCP Server

[![Model Context Protocol](https://img.shields.io/badge/MCP-Streamable%20HTTP-blue.svg)](https://modelcontextprotocol.io/)
[![Google Cloud Run](https://img.shields.io/badge/Google%20Cloud-Cloud%20Run-4285F4.svg?logo=google-cloud)](https://cloud.google.com/run)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)

A production-ready **Model Context Protocol (MCP)** server providing comprehensive integration with **Google Threat Intelligence (GTI)** and **VirusTotal API v3**. Built with high-performance async Python, FastAPI, and MCP Streamable HTTP transport standard (`/mcp`), designed for deployment on **Google Cloud Run** and seamless interaction with **Gemini Enterprise** and AI Security Agents.

---

## 🌟 Key Features

- **Streamable HTTP Transport (`/mcp`)**: Native support for the MCP Streamable HTTP protocol specification with zero-redirect routing.
- **22+ Threat Intelligence Tools**: Direct access to Google Threat Intelligence collections, Threat Actors, Campaigns, Malware Families, Reports, File Sandbox Analyses, IP/Domain/URL telemetry, and IoC lookups.
- **Enterprise Security**: Native integration with **Google Cloud Secret Manager** (`VT_APIKEY` / `VT_SECRET_NAME`) ensures no secrets or API keys are stored in source code.
- **Gemini Enterprise & Agent Ready**: IAM-protected endpoints (`roles/run.invoker`) with Google Cloud identity authentication.
- **Automated Cloud Deployment**: One-command build and deployment script (`deploy.sh`) with Google Cloud Build and Cloud Run.

---

## 🛠️ MCP Tool Suite

| Category | Available Tools |
| :--- | :--- |
| **Threat Landscape & Collections** | `search_threat_actors`, `get_threat_actor`, `search_campaigns`, `get_campaign`, `search_malware_families`, `get_malware_family`, `search_reports`, `get_threat_report` |
| **File & IoC Telemetry** | `get_file_report`, `get_file_behaviour`, `search_ioc`, `get_file_sigma_analysis`, `get_file_yara_rules` |
| **Network Infrastructure** | `get_ip_report`, `get_domain_report`, `get_url_report`, `get_ip_communicating_files`, `get_domain_communicating_files`, `get_ip_historical_ssl`, `get_domain_subdomains` |
| **Diagnostics & Health** | `health_check`, `get_server_status` |

---

## 🚀 Quick Start

### 1. Prerequisites

- Python 3.10+
- Google Cloud SDK (`gcloud`) configured with project access
- Valid Google Threat Intelligence / VirusTotal API Key

### 2. Local Setup

Clone the repository and install dependencies:

```bash
git clone https://github.com/yayefa/GTI-MCP-Server.git
cd GTI-MCP-Server

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### 3. Environment Configuration

Copy the sample environment file:

```bash
cp .env.example .env
```

Edit `.env` to configure your settings:

```dotenv
PROJECT_ID=your-gcp-project-id
REGION=us-central1
SERVICE_NAME=mcp-gti-mcp-server
VT_SECRET_NAME=VT_APIKEY
SECRET_PROJECT_ID=your-gcp-project-id
LOG_LEVEL=INFO
```

### 4. Running Locally

```bash
uvicorn server:app --host 0.0.0.0 --port 8080 --reload
```

---

## ☁️ Deployment to Google Cloud Run

### 1. Store API Key in Google Secret Manager

```bash
echo -n "YOUR_GTI_VT_API_KEY" | gcloud secrets create "VT_APIKEY" \
    --data-file=- \
    --project="YOUR_PROJECT_ID" \
    --replication-policy="automatic"
```

### 2. Deploy via Script

Execute the automated deployment script:

```bash
chmod +x deploy.sh
./deploy.sh
```

For complete deployment details and IAM configuration, see [DEPLOYMENT.md](DEPLOYMENT.md).

---

## 🧪 Testing and Verification

Run the automated test client against your running instance or deployed Cloud Run service:

```bash
AUTH_TOKEN=$(gcloud auth print-identity-token) \
TARGET_URL="https://<YOUR-CLOUD-RUN-URL>" \
python3 test_client.py
```

Or query the MCP endpoint directly using `curl`:

```bash
curl -X POST https://<YOUR-CLOUD-RUN-URL>/mcp \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "get_ip_report",
      "arguments": {
        "ip_address": "8.8.8.8"
      }
    }
  }'
```

---

## 📄 License

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