# snyk-mcp-rest
[](https://opensource.org/licenses/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](https://www.linkedin.com/in/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
```bash
npm install
```
## Build
The build process includes OpenAPI code generation and TypeScript compilation:
```bash
# 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
```typescript
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
```bash
# 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:**
```bash
npx ts-node examples/list-tools.ts
```
This will show both Snyk CLI tools and REST API tools.
**Testing REST API tools:**
```bash
# 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:**
```bash
# 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)**
```json
{
"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:
```json
{
"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:
```bash
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](https://docs.snyk.io/snyk-cli/commands) 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:
```typescript
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:
```bash
# 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
```text
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:
```typescript
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:
```env
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:
```env
SNYK_CLI_PROXY_ENABLED=false
```
Or set it in your Claude Desktop configuration:
```json
{
"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
