Skip to content

axelspringer/snyk-mcp-rest

BranchesTags

Repository files navigation

snyk-mcp-rest

License: MIT

TypeScript client for the Snyk REST API with built-in Model Context Protocol (MCP) server support. This package provides both a type-safe API client auto-generated from the official Snyk OpenAPI specification and a comprehensive MCP server that exposes both Snyk CLI tools and REST API tools for AI assistant integrations.

Paul Hackenberger

Architecture

This MCP server provides a unified interface to Snyk security scanning through two complementary tool sets:

🔧 Snyk CLI Tools (via Proxy)

The server automatically connects to the Snyk CLI and proxies all native CLI commands as MCP tools. These tools provide comprehensive security scanning capabilities:

  • snyk_test - Test projects for vulnerabilities
  • snyk_code_test - Static code analysis for security issues
  • snyk_container_test - Container image scanning
  • snyk_iac_test - Infrastructure as Code scanning
  • snyk_monitor - Monitor projects in Snyk dashboard
  • snyk_sbom_test - SBOM generation and testing
  • snyk_send_feedback - Report security metrics
  • snyk_trust, snyk_version, and more

🌐 REST API Tools (Custom)

Additionally, the server provides custom-built tools using the Snyk REST API for management and querying operations:

  • snyk_rest_find_projects - Search for projects by name
  • snyk_rest_get_issues - Retrieve issues for a project
  • snyk_rest_get_issue - Get detailed issue information
  • snyk_rest_get_repo_issues - Aggregate issues across repository projects

This dual-tool architecture gives AI assistants the best of both worlds: the full power of Snyk CLI for scanning operations, combined with efficient REST API access for querying and management tasks.

Features

  • 🔄 Auto-generated TypeScript Client - Generated from official Snyk OpenAPI spec
  • 🤖 MCP Server Integration - Built-in Model Context Protocol server for AI assistants (Claude, etc.)
  • 📦 Complete Type Safety - Full TypeScript support with IntelliSense
  • 🔌 Axios-based HTTP Client - Reliable HTTP operations with error handling
  • 🧪 Comprehensive Testing - Vitest with coverage support
  • 🏗️ Modular Architecture - Clean separation between generated and custom code

Installation

npm install

Build

The build process includes OpenAPI code generation and TypeScript compilation:

# Full build (generate + compile)
npm run prepare

# Generate API client from OpenAPI spec
npm run generate

# Compile TypeScript only
npm run build

Usage

Basic API Client Usage

import { Configuration, OrgsApi, IssuesApi } from "snyk-mcp-rest";

// Configure API client
const config = new Configuration({
  apiKey: process.env.SNYK_API_KEY,
  basePath: "https://api.snyk.io/rest",
});

// Or use the helper function
import { createConfiguration } from "snyk-mcp-rest";
const config = createConfiguration(process.env.SNYK_API_KEY!);

// Use Organizations API
const orgsApi = new OrgsApi(config);
const orgs = await orgsApi.listOrgs({
  version: "2024-11-05",
});

// Use Issues API
const issuesApi = new IssuesApi(config);
const issues = await issuesApi.listOrgIssues({
  version: "2024-11-05",
  orgId: "your-org-id",
  status: ["open"],
  limit: 100,
});

// Use Projects API to find projects by repository name
const projectsApi = new ProjectsApi(config);
const projects = await projectsApi.listOrgProjects({
  version: "2024-11-05",
  orgId: "your-org-id",
  names: ["owner/my-repo"], // Filter by repository name
});

// Get project IDs from matching repositories
const projectIds = projects.data.data?.map((p) => p.id) || [];

// Fetch issues for specific projects
if (projectIds.length > 0) {
  const projectIssues = await issuesApi.listOrgIssues({
    version: "2024-11-05",
    orgId: "your-org-id",
    scanItemId: projectIds[0],
    scanItemType: "project" as any,
    status: ["open"],
  });
}

MCP Server Usage

The MCP server provides AI assistants with access to Snyk security data. Configure it in your AI assistant (e.g., Claude Desktop):

Starting the MCP Server

# Development mode (with ts-node)
npm run mcp-server

# Production mode (requires build first)
npm run build
npm run mcp-server:build

Testing the MCP Server

Test the MCP server without Claude Desktop using the provided test scripts:

List all available tools:

npx ts-node examples/list-tools.ts

This will show both Snyk CLI tools and REST API tools.

Testing REST API tools:

# Build the project first
npm run build

# Test snyk_rest_get_issues tool
npx ts-node examples/snyk-rest-get-issues.ts [project-id] [status] [severity]

# Examples:
npx ts-node examples/snyk-rest-get-issues.ts                                          # All open issues
npx ts-node examples/snyk-rest-get-issues.ts 12345678-1234-1234-1234-123456789012    # Open issues for specific project
npx ts-node examples/snyk-rest-get-issues.ts 12345678-1234-1234-1234-123456789012 resolved  # Resolved issues for project
npx ts-node examples/snyk-rest-get-issues.ts 12345678-1234-1234-1234-123456789012 open critical  # Critical open issues
npx ts-node examples/snyk-rest-get-issues.ts "" resolved high                         # All resolved high severity issues

The snyk-rest-get-issues.ts script accepts the same parameters as the snyk_rest_get_issues MCP tool:

  • projectId - Project ID in UUID format (optional)
  • status - Issue status: open, resolved, ignored (optional, default: open)
  • severity - Issue severity: low, medium, high, critical (optional)

Testing snyk_rest_get_issue tool:

# Get detailed information about a specific issue
npx ts-node examples/snyk-rest-get-issue.ts <issue-id>

# Example:
npx ts-node examples/snyk-rest-get-issue.ts 12345678-1234-1234-1234-123456789012

The snyk-rest-get-issue.ts script requires:

  • issue_id - The unique identifier (UUID) of the issue to retrieve (required)

Claude Desktop Configuration

Add to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

Option 1: Using npx with ts-node (recommended for development)

{
  "mcpServers": {
    "snyk-rest-api": {
      "command": "npx",
      "args": [
        "-y",
        "ts-node",
        "/absolute/path/to/snyk-mcp-rest/src/mcp-server.ts"
      ],
      "env": {
        "SNYK_API_KEY": "your-snyk-api-key-here",
        "SNYK_ORG_ID": "your-org-id-uuid-here",
        "SNYK_ORG_SLUG": "your-org-slug-here"
      }
    }
  }
}

Option 2: Using compiled JavaScript (recommended for production)

Build the project first with npm run build, then:

{
  "mcpServers": {
    "snyk-rest-api": {
      "command": "node",
      "args": ["/absolute/path/to/snyk-mcp-rest/dist/mcp-server.js"],
      "env": {
        "SNYK_API_KEY": "your-snyk-api-key-here",
        "SNYK_ORG_ID": "your-org-id-uuid-here",
        "SNYK_ORG_SLUG": "your-org-slug-here"
      }
    }
  }
}

Important: Replace /absolute/path/to/snyk-mcp-rest with the actual absolute path to your project directory (e.g., /Users/yourname/Projects/snyk-mcp-rest).

Available MCP Tools

The MCP server provides two types of tools:

Snyk CLI Tools

All native Snyk CLI commands are available as MCP tools with the snyk_ prefix. For a complete list of available CLI tools and their parameters, run:

npx ts-node examples/list-tools.ts

Key CLI tools include:

  • snyk_test - Test projects for open source vulnerabilities
  • snyk_code_test - Static application security testing (SAST)
  • snyk_container_test - Container and Kubernetes security scanning
  • snyk_iac_test - Infrastructure as Code scanning
  • snyk_monitor - Snapshot and continuously monitor projects
  • snyk_sbom_test - Generate and test Software Bill of Materials

Refer to the official Snyk CLI documentation for detailed usage of each CLI tool.

REST API Tools

Custom tools built using the Snyk REST API for querying and management:

  • snyk_rest_find_projects - Search for Snyk projects by name using the Snyk REST API

    • Parameters:
      • query (required): Search query string to match against project names
    • Configuration (via environment variables):
      • SNYK_ORG_ID (required): Snyk Organization ID (UUID)
    • Returns: List of projects with their IDs and names

  • snyk_rest_get_issues - Retrieve Snyk security issues for an organization and project using the Snyk REST API

    • SNYK_ORG_ID (required): Snyk Organization ID (UUID)
    • SNYK_ORG_SLUG (required): Organization slug for URLs
    • Returns: Formatted issues with direct Snyk URLs. The repository field will be null unless explicitly provided by specialized tools like snyk_rest_get_repo_issues

    Note: The projectId parameter must be in UUID format. To find the Project ID for a repository:

    const projectsApi = new ProjectsApi(config);
const projects = await projectsApi.listOrgProjects({
  version: "2024-11-05",
  orgId: "your-org-id",
  names: ["owner/my-repo"],
});
const projectId = projects.data.data?.[0]?.id;

Available APIs

The client provides access to all Snyk REST API endpoints:

  • AccessRequestsApi - Manage access requests
  • AppsApi - Snyk Apps management
  • AuditLogsApi - Audit log access
  • CloudApi - Cloud security operations
  • ContainerImageApi - Container image scanning
  • CustomBaseImagesApi - Custom base image management
  • FindingsApi - Security findings
  • GroupsApi / GroupApi - Group management
  • IacSettingsApi - Infrastructure as Code settings
  • InvitesApi - User invitations
  • IssuesApi - Security issues management
  • OrgsApi - Organization operations
  • PoliciesApi - Policy management
  • ProjectsApi - Project operations
  • SbomApi - Software Bill of Materials
  • ServiceAccountsApi - Service account management
  • SlackApi / SlackSettingsApi - Slack integration
  • TargetsApi - Target management
  • TenantsApi - Tenant operations
  • TestsApi - Testing operations
  • UsersApi - User management

...and many more! See src/generated/api/ for the complete list.

Development

Running Tests

The project includes comprehensive test coverage:

# Run all tests once
npm test

# Watch mode (auto-rerun on changes)
npm run test:watch

# Coverage report
npm run test:coverage

# UI mode (interactive test runner)
npm run test:ui

Test Suites

  • API Client Tests (tests/api.test.ts) - Configuration, API instantiation, exports (18 tests)
  • MCP Server Tests (tests/mcp-server.test.ts) - Issue retrieval, filtering, pagination, project name fetching (9 tests)
  • MCP Server Logic Tests (tests/mcp-server-logic.test.ts) - Handler functions, tool schema (21 tests)
  • MCP Business Logic Tests (tests/mcp-business-logic.test.ts) - Issue formatting, response handling (25 tests)
  • Integration Tests (tests/integration.test.ts) - Multi-API workflows, pagination handling (7 tests)
  • Error Handling Tests (tests/error-handling.test.ts) - HTTP errors, network failures, validation (8 tests)
  • Index Exports Tests (tests/index.test.ts) - Module exports and type definitions (14 tests)

Test Statistics: 102 test cases across 7 test files covering core functionality, error scenarios, and edge cases.

Coverage: 93%+ overall code coverage (100% for src/index.ts, 93%+ for src/mcp-server.ts). Generated code (src/generated/**) is excluded from coverage as per project policy.

Project Structure

src/
├── generated/          # Auto-generated (DO NOT EDIT)
│   ├── api/           # API classes
│   ├── models/        # TypeScript interfaces
│   └── configuration.ts, base.ts, common.ts
├── index.ts           # Main entry point - API client exports
├── mcp-server.ts      # MCP server (business logic + startup script)
└── tools/             # MCP tool implementations
    ├── index.ts       # Tool registry
    ├── types.ts       # Tool type definitions
    ├── utils.ts       # Shared utilities
    ├── snyk-rest-get-issues.ts  # snyk_rest_get_issues tool
    ├── snyk-rest-get-issue.ts   # snyk_rest_get_issue tool
    ├── snyk-rest-get-repo-issues.ts  # snyk_rest_get_repo_issues tool
    └── snyk-rest-find-projects.ts    # snyk_rest_find_projects tool
examples/
├── basic-usage.ts     # Basic API client usage example
├── snyk-rest-get-issues.ts      # MCP server testing script (snyk_rest_get_issues tool)
├── snyk-rest-get-issue.ts       # MCP server testing script (snyk_rest_get_issue tool)
├── snyk-rest-get-repo-issues.ts # MCP server testing script (snyk_rest_get_repo_issues tool)
└── snyk-rest-find-projects.ts   # MCP server testing script (snyk_rest_find_projects tool)
tests/
├── api.test.ts                    # API client tests (18 tests)
├── mcp-server.test.ts             # MCP server integration tests (9 tests)
├── mcp-server-logic.test.ts       # MCP handler functions (21 tests)
├── mcp-business-logic.test.ts     # Issue formatting logic (25 tests)
├── integration.test.ts            # Multi-API workflows (7 tests)
├── error-handling.test.ts         # Error scenarios (8 tests)
└── index.test.ts                  # Module exports (14 tests)
res/
└── v1-api-spec.yaml  # OpenAPI specification

Important: Never edit files in src/generated/ - they are auto-generated from the OpenAPI spec.

Error Handling

The client uses Axios for HTTP operations. Handle errors appropriately:

import { AxiosError } from "axios";

try {
  const response = await issuesApi.listOrgIssues({
    version: "2024-11-05",
    orgId: "your-org-id",
  });
} catch (error) {
  if (error instanceof AxiosError) {
    console.error("API Error:", error.response?.status);
    console.error("Details:", error.response?.data);
  } else {
    console.error("Unexpected error:", error);
  }
}

Environment Variables

Create a .env file in the project root:

SNYK_API_KEY=your-api-key-here

For the MCP server, these environment variables are used:

  • SNYK_API_KEY (required) - Your Snyk API token (get from https://app.snyk.io/account)
  • SNYK_ORG_ID (required) - Your Snyk Organization ID (UUID format)
  • SNYK_ORG_SLUG (required) - Your Snyk Organization slug for URLs (e.g., my-org)
  • SNYK_CLI_PROXY_ENABLED (optional) - Enable/disable Snyk CLI tool proxying (default: true)
    • Set to false, 0, or no to disable Snyk CLI tools and only use REST API tools
    • When disabled, only custom REST API tools (snyk_rest_*) will be available
    • When enabled (default), both Snyk CLI tools and REST API tools are available

You can find your Organization ID and slug in the Snyk web UI under your organization settings.

Example: Disabling Snyk CLI Proxy

If you want to use only the REST API tools and disable the Snyk CLI proxy, add this to your .env file:

SNYK_CLI_PROXY_ENABLED=false

Or set it in your Claude Desktop configuration:

{
  "mcpServers": {
    "snyk-rest-api": {
      "command": "node",
      "args": ["/absolute/path/to/snyk-mcp-rest/dist/mcp-server.js"],
      "env": {
        "SNYK_API_KEY": "your-snyk-api-key-here",
        "SNYK_ORG_ID": "your-org-id-uuid-here",
        "SNYK_ORG_SLUG": "your-org-slug-here",
        "SNYK_CLI_PROXY_ENABLED": "false"
      }
    }
  }
}

Version Information

  • API Version: Uses Snyk REST API version 2024-11-05 (all API calls require version parameter)
  • OpenAPI Spec: Generated from v1-api-spec.yaml
  • TypeScript: 5.9+
  • Node.js: Compatible with modern Node.js versions (ES2020 target)

Configuration

Code generation is configured via openapitools.json:

  • Template: typescript-axios
  • Single request parameter: Enabled
  • Separate models and API: Enabled
  • Output: ./src/generated

License

MIT

Repository

https://github.com/axelspringer/snyk-mcp-rest

Contributing

  1. Make changes to custom code (not src/generated/)
  2. Update OpenAPI spec or generator config if needed
  3. Run npm test to verify changes
  4. Update this README if adding new features

About

MCP for Snyk REST API

Resources

Readme

License

MIT license
Activity
Custom properties

Stars

2 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

No packages published

Languages