GreyNoise-Intelligence/greynoise-mcp-server

MCP Server For GreyNoise

REQUIRES AN ENTERPRISE API KEY

Installation

For Development

Clone the whole repo and then npm install && npm run build.

For Production/NPX Usage

npx @greynoise/greynoise-mcp-server --help

Note: The bundled version works standalone for stdio transport (default). HTTP transport requires Express to be available.

This is a sample entry for, say, Claude Desktop:

{
  "mcpServers": {
    "greynoise": {
      "command": "npx",
      "args": ["@greynoise/greynoise-mcp-server"],
      "env": {
        "GREYNOISE_API_KEY": "your-greynoise-api-key"
      }
    }
  }
}

Or for local development:

{
  "mcpServers": {
    "greynoise": {
      "command": "node",
      "args": ["/absolute/path/to/greynoise-mcp-server/build/index.js"],
      "env": {
        "GREYNOISE_API_KEY": "your-greynoise-api-key"
      }
    }
  }
}

Build System

This project uses tsup for modern bundling:

• npm run build: Creates optimized bundle for distribution
• npm run build:dev: Development build with source maps
• npm run dev: Watch mode with auto-rebuild
• npm run build:standalone: Prepares package for NPX distribution

The bundled output includes all core dependencies except Express (for HTTP transport) and dotenv (due to dynamic require limitations).

Testing

The project includes a test script for verifying the GreyNoise API endpoints directly:

Prerequisites

1. Build the project:

   npm run build
   

2. Set your GreyNoise Enterprise API key:

   # For Linux/macOS
   export GREYNOISE_API_KEY=your-api-key-here
   
   # For Windows Command Prompt
   set GREYNOISE_API_KEY=your-api-key-here
   
   # For Windows PowerShell
   $env:GREYNOISE_API_KEY="your-api-key-here"
   

Running Tests

# Test all API endpoints
node test-tools.js

# Test a specific API endpoint
node test-tools.js ip-context
node test-tools.js quick-check-ip
node test-tools.js multi-ip-check
node test-tools.js riot-lookup
node test-tools.js tag-list
node test-tools.js tag-details
node test-tools.js tag-activity
node test-tools.js trending-tags
node test-tools.js gnql-stats
node test-tools.js cve-details

The test script directly verifies the GreyNoise API endpoints without using the MCP server layer. This helps to:

1. Confirm your API key works correctly
2. Verify connectivity to the GreyNoise API
3. Validate the expected response formats
4. Troubleshoot specific endpoints independently

Implementation Notes

The test script mimics how the actual MCP tools access the API with some key differences:

• Tag List & Details: First retrieves all tags via v3/tags and uses client-side filtering for specific tags
• Tag Activity: Requires the tag ID (not slug), so it first looks up the tag's details before retrieving activity data
• Trending Tags: Combines data from two endpoints: v3/summary/tags?sort=trending and v3/summary/tags?sort=anomalies
• Multi-IP Check: Uses a special POST method rather than the standard GET requests

MCP Tools and Prompts

This MCP server provides comprehensive access to GreyNoise Intelligence data about internet-scanning IP addresses, threat actors, and vulnerabilities. It includes tools for IP analysis (detailed context, quick checks, batch processing, and business service lookups), tag exploration, vulnerability tracking, and query capabilities.

Transport Options

stdio (Default)

The bundled version works completely standalone for stdio transport:

npx @greynoise/greynoise-mcp-server --transport stdio

http

HTTP transport requires Express to be available in the environment:

# Ensure Express is available
npm install express
npx @greynoise/greynoise-mcp-server --transport http

Available Tools

1. lookup-ip-context - Get detailed GreyNoise context information about an IP address

2. quick-check-ip - Get a fast, lightweight check of an IP address to determine if it's scanning the internet or is a common business service (uses v2/noise/quick/{ip})

3. multi-ip-check - Check multiple IP addresses at once (up to 100) for noise and common business service status (uses v2/noise/multi/quick with POST)

4. riot-lookup - Check if an IP address belongs to a common business service and get detailed information about the service (uses v2/riot/{ip})

5. get-tag-list - Retrieve the complete list of GreyNoise tags with metadata including identifiers, descriptions, categories, and intentions

6. search-tags - Search for GreyNoise tags matching a specific query

7. get-tag-details - Get comprehensive metadata about a specific GreyNoise tag

8. get-tag-activity - Get activity data for a specific GreyNoise tag, including trends over time

9. analyze-tags-activity - Analyze activity patterns across multiple tags to identify correlations and trends

10. get-trending-vulnerabilities - Get information on vulnerabilities actively being exploited in the wild, as detected by GreyNoise

11. gnql-stats - Query GreyNoise's database using the GreyNoise Query Language (GNQL) and retrieve statistical data

12. get-cve-details - Get detailed information about a specific CVE, including GreyNoise observations of exploitation attempts

Usage Examples

IP Analysis Tools

// Quick check for a single IP
{
  "tool_name": "quick-check-ip",
  "parameters": {
    "ip": "8.8.8.8"
  }
}

// Check multiple IPs at once (up to 100)
{
  "tool_name": "multi-ip-check",
  "parameters": {
    "ips": ["8.8.8.8", "1.1.1.1", "205.251.242.103"]
  }
}

// Look up business service information
{
  "tool_name": "riot-lookup",
  "parameters": {
    "ip": "8.8.8.8"
  }
}

// Get detailed context for an IP
{
  "tool_name": "lookup-ip-context",
  "parameters": {
    "ip": "89.248.165.191"
  }
}

// Get tags and filter for a specific one
{
  "tool_name": "get-tag-details",
  "parameters": {
    "id_or_slug": "scanner"
  }
}

// Get tag activity data (by tag ID or by CVE)
{
  "tool_name": "get-tag-activity",
  "parameters": {
    "id_or_slug": "scanner",
    "days": "30"
  }
}

// Get trending vulnerability tags
{
  "tool_name": "get-trending-vulnerabilities",
  "parameters": {}
}

Available Prompts

1. vendor-threat-report - Generate a comprehensive threat report for a vendor technology
   • Produces a detailed analysis including executive summary, threat actor activity, recent vulnerabilities, attack patterns, mitigation recommendations, and confidence assessment
   • Automatically orchestrates multiple GreyNoise data queries to assemble a complete picture of the threat landscape