# mcp-greynoise

[![npm version](https://img.shields.io/npm/v/mcp-greynoise.svg)](https://www.npmjs.com/package/mcp-greynoise)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

MCP server for the [GreyNoise](https://greynoise.io) API — check if IP addresses are internet background noise or potentially targeted attacks.

## Quick Start

```bash
npx mcp-greynoise
```

That's it. Works out of the box with 10 lookups/day (no API key needed).

## What is GreyNoise?

GreyNoise collects and analyzes internet-wide scan traffic. It tells you:

- **Noise**: Is this IP mass-scanning the internet? (botnets, researchers, crawlers)
- **RIOT**: Is this IP a known benign service? (Google, Cloudflare, Microsoft, etc.)
- **Classification**: Malicious, benign, or unknown

### Why this matters for security

When you see suspicious traffic in your logs:

| GreyNoise Result | Interpretation |
|------------------|----------------|
| **NOISE + Malicious** | Background attack traffic (scanners, botnets) — likely untargeted |
| **NOISE + Benign** | Security researchers, search crawlers — usually safe |
| **RIOT** | Known good service (CDN, DNS, cloud) — almost certainly benign |
| **NOT NOISE** | ⚠️ This IP is NOT mass-scanning — traffic may be **targeted at you** |

The "NOT NOISE" case is often the most important — it suggests someone is specifically interested in your systems.

## Demo

<!-- TODO: Add GIF of Claude Desktop calling check_ip -->

**Example output from `check_ip`:**

```
IP: 51.91.185.74
Classification: MALICIOUS
Noise: YES - This IP has been observed scanning the internet
RIOT: NO - Not a known benign service IP
Last Seen: 2024-01-15
Details: https://viz.greynoise.io/ip/51.91.185.74

--- Interpretation ---
🚨 This IP is actively scanning the internet and classified as MALICIOUS. 
   Likely a scanner, botnet, or threat actor.
```

## Installation

### npm (recommended)

```bash
npm install -g mcp-greynoise
```

### npx (no install)

```bash
npx mcp-greynoise
```

### From source

```bash
git clone https://github.com/nickjlucker/mcp-greynoise.git
cd mcp-greynoise
npm install
npm run build
node build/index.js
```

## Configuration

### Claude Desktop

Add to your `claude_desktop_config.json`:

**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "greynoise": {
      "command": "npx",
      "args": ["mcp-greynoise"],
      "env": {
        "GREYNOISE_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `GREYNOISE_API_KEY` | No | API key for higher rate limits (50/day vs 10/day) |

Get a free API key at [viz.greynoise.io/signup](https://viz.greynoise.io/signup).

> ⚠️ **Never commit API keys.** See `.env.example` for the recommended setup.

## Tools

### `check_ip`

Check a single IP address against GreyNoise.

**Input:**
- `ip` (string): IPv4 address to check

### `check_ips`

Check multiple IP addresses in one call (max 10).

**Input:**
- `ips` (string[]): Array of IPv4 addresses

**Example output:**
```
=== Results ===
8.8.8.8: RIOT (benign service) [Google]
51.91.185.74: NOISE - MALICIOUS
192.168.1.1: NOT NOISE (potentially targeted)

--- Legend ---
RIOT: Known benign service (CDN, DNS, etc.)
NOISE: IP is mass-scanning the internet
NOT NOISE: IP is NOT mass-scanning (traffic may be targeted)
```

## Resources

### `greynoise://status`

Returns API status and rate limit information.

## Rate Limits

| Tier | Daily Lookups |
|------|---------------|
| Unauthenticated | 10 |
| Free account | 50 |
| Paid plans | Higher |

Rate limits are shared between API calls and the [GreyNoise Visualizer](https://viz.greynoise.io).

## Security

This server:
- **Only reads** from the GreyNoise API (no scanning, no exploitation)
- **Does not store** any data beyond the current request
- **Does not transmit** your API key anywhere except to GreyNoise
- Performs **reputation/telemetry enrichment only**

Your API key is passed via environment variable and never logged.

## Use Cases

- **SOC Triage**: Quickly determine if alert IPs are background noise or targeted
- **Incident Response**: Identify if attacker IPs are mass-scanners or focused threats
- **Threat Hunting**: Find IPs in your logs that aren't mass-scanners (potentially targeted)
- **Log Analysis**: Reduce false positives by filtering out known scanners

## Development

```bash
# Install dependencies
npm install

# Run in development mode
npm run dev

# Build for production
npm run build

# Run built version
npm start
```

## License

MIT

## Links

- [GreyNoise](https://greynoise.io)
- [GreyNoise API Docs](https://docs.greynoise.io)
- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP Registry](https://registry.modelcontextprotocol.io)