FOSSA

MCP

Query Software Bill of Materials (SBOM), license compliance, and dependency data from FOSSA using AI assistants.

Overview

The FOSSA molecule provides Model Context Protocol (MCP) integration for retrieving software composition analysis data from FOSSA. It enables AI assistants like Claude to query SBOMs, licenses, dependencies, and security issues.

Key Features:

• Download SBOMs in multiple formats (CycloneDX, SPDX)
• Retrieve license and attribution data
• Query project dependencies with license information
• Track security vulnerabilities and compliance issues
• List and filter FOSSA projects

Note: This is an MCP-only molecule (no discovery component).

Quick Start

Configure the FOSSA MCP server:

mcp:
  fossa:
    api_token: ${FOSSA_API_TOKEN}
    base_url: https://app.fossa.com/api  # Optional

Configuration

Basic Configuration

mcp:
  fossa:
    api_token: ${FOSSA_API_TOKEN}

Self-Hosted FOSSA

mcp:
  fossa:
    api_token: ${FOSSA_API_TOKEN}
    base_url: https://fossa.company.com/api

Configuration Options

Option	Type	Required	Default	Description
api_token	string	Yes	-	FOSSA API authentication token
base_url	string	No	https://app.fossa.com/api	FOSSA API base URL

Authentication

Getting a FOSSA API Token

1. Log in to FOSSA
2. Go to Settings → API Tokens
3. Click "Create New Token"
4. Give it a name (e.g., "Devgraph MCP")
5. Select appropriate permissions
6. Copy the token

Set environment variable:

export FOSSA_API_TOKEN="your-fossa-token-here"

MCP Tools

list_projects

List all FOSSA projects with optional filtering.

Parameters:

• filter_title (optional): Filter by project title
• limit (optional): Maximum results (default: 100)
• offset (optional): Pagination offset (default: 0)

Example via Claude:

List all FOSSA projects with "backend" in the title

Response:

{
  "projects": [
    {
      "id": "custom+1/backend-api",
      "title": "Backend API",
      "url": "https://github.com/myorg/backend-api",
      "default_branch": "main"
    }
  ]
}

get_project_sbom

Download a Software Bill of Materials for a project revision.

Parameters:

• revision_id (required): Project revision ID (e.g., "custom+1/my-project/main")
• format (optional): SBOM format (default: "cyclonedx-json")
• include_deep_dependencies (optional): Include transitive deps (default: true)

Supported Formats:

• cyclonedx-json - CycloneDX JSON format (OWASP standard)
• cyclonedx-xml - CycloneDX XML format
• spdx-json - SPDX JSON format (Linux Foundation standard)
• spdx-tag-value - SPDX Tag-Value format

Example via Claude:

Get the SBOM for backend-api main branch in CycloneDX JSON format

Response: Full SBOM in requested format with components, licenses, and dependencies.

get_project_licenses

Retrieve license information and attribution data for a project.

Parameters:

• revision_id (required): Project revision ID

Example via Claude:

What licenses are used in the backend-api project?

Response:

{
  "licenses": [
    {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT",
      "components": ["lodash@4.17.21", "express@4.18.0"]
    },
    {
      "name": "Apache-2.0",
      "url": "https://apache.org/licenses/LICENSE-2.0",
      "components": ["typescript@5.0.0"]
    }
  ]
}

get_project_dependencies

Get detailed dependency information for a project revision.

Parameters:

• revision_id (required): Project revision ID

Example via Claude:

Show me all dependencies for backend-api including their licenses

Response:

{
  "dependencies": [
    {
      "name": "lodash",
      "version": "4.17.21",
      "license": "MIT",
      "direct": true
    },
    {
      "name": "express",
      "version": "4.18.0",
      "license": "MIT",
      "direct": true
    }
  ]
}

get_project_issues

Query security vulnerabilities and compliance issues.

Parameters:

• project_id (required): Project ID
• issue_type (optional): Filter by type ("vulnerability", "license", "quality")

Example via Claude:

What security vulnerabilities does backend-api have?

Response:

{
  "issues": [
    {
      "type": "vulnerability",
      "severity": "HIGH",
      "title": "Prototype Pollution in lodash",
      "description": "CVE-2020-8203",
      "component": "lodash@4.17.15",
      "remediation": "Upgrade to lodash@4.17.21"
    }
  ]
}

Usage Examples

Via Claude Desktop

After configuring the FOSSA MCP server, interact with Claude:

Get SBOM

Download the SBOM for my-backend-service in SPDX JSON format

Check Licenses

What licenses are we using in the frontend-app project?
Are there any GPL licenses in our codebase?

Analyze Dependencies

Show me all dependencies for backend-api
Which dependencies use the MIT license?

Security Vulnerabilities

What security vulnerabilities does backend-api have?
List all high-severity issues in our projects

Compliance Checks

Are there any license compliance issues in frontend-app?
Which projects have GPL dependencies?

SBOM Formats

CycloneDX

JSON Format (Recommended):

format: cyclonedx-json

XML Format:

format: cyclonedx-xml

CycloneDX is an OWASP standard focused on security and component analysis.

SPDX

JSON Format:

format: spdx-json

Tag-Value Format:

format: spdx-tag-value

SPDX is a Linux Foundation standard focused on licensing and compliance.

Revision ID Format

FOSSA uses a specific format for revision IDs:

<fetcher>+<org_id>/<project>/<branch>

Examples:

• custom+1/my-project/main
• git+github.com/myorg/my-repo/develop
• custom+5/backend-api/release/v1.0

Components:

• fetcher: How code is fetched (custom, git, etc.)
• org_id: Organization ID in FOSSA
• project: Project name
• branch: Branch or version

Use Cases

License Compliance

Ensure all dependencies meet licensing requirements:

Check all projects for GPL licenses
Get attribution report for backend-api

Security Auditing

Track vulnerabilities across projects:

List all high-severity vulnerabilities
Which projects have unpatched CVEs?

Dependency Management

Analyze dependency usage:

What version of lodash is backend-api using?
Show all projects using vulnerable dependencies

SBOM Generation

Generate SBOMs for compliance and documentation:

Download SBOM for all production projects in SPDX format
Generate CycloneDX SBOM for security audit

Supply Chain Security

Track software supply chain:

Map all dependencies for critical services
Identify shared dependencies across projects

Troubleshooting

Authentication Errors

Symptom: "401 Unauthorized" or "403 Forbidden"

Solutions:

1. Verify API token is correct
2. Check token hasn't expired
3. Ensure token has required permissions
4. For self-hosted: Verify base URL is correct

Project Not Found

Symptom: "Project not found" error

Solutions:

1. Verify revision ID format is correct
2. Check project exists in FOSSA
3. Ensure branch/tag exists
4. Use list_projects to find correct ID

Invalid Revision ID

Symptom: "Invalid revision ID" error

Solutions:

1. Use correct format: fetcher+org_id/project/branch
2. Check for typos in project or branch name
3. Verify org_id is correct
4. Try with default branch first

SBOM Format Not Supported

Symptom: "Unsupported format" error

Solutions:

1. Use supported formats: cyclonedx-json, cyclonedx-xml, spdx-json, spdx-tag-value
2. Check FOSSA version supports requested format
3. Try default format (cyclonedx-json)

Missing Dependencies

Symptom: Dependencies not appearing in results

Solutions:

1. Ensure project has been scanned by FOSSA
2. Check scan completed successfully
3. For deep dependencies: Use include_deep_dependencies: true
4. Re-scan project if needed

Integration Examples

CI/CD Integration

Use FOSSA MCP in CI/CD pipelines:

1. Generate SBOM after build
2. Check for vulnerabilities before deploy
3. Verify license compliance
4. Block on policy violations

Development Workflow

Integrate into development:

1. Query licenses before adding dependencies
2. Check security issues during code review
3. Generate SBOMs for releases
4. Track dependency updates

Compliance Reporting

Automate compliance workflows:

1. Generate attribution reports
2. Export SBOMs for customers
3. Track license obligations
4. Audit third-party code

Best Practices

1. Regular Scans: Scan projects frequently in FOSSA
2. Branch Strategy: Track main/production branches
3. Format Selection: Use CycloneDX for security, SPDX for licensing
4. Deep Dependencies: Include transitive dependencies
5. Issue Tracking: Monitor vulnerabilities continuously
6. Policy Enforcement: Set up FOSSA policies
7. Documentation: Document license compliance decisions

Performance Tips

1. Specific Queries: Use filters to narrow results
2. Pagination: Use offset/limit for large result sets
3. Format Selection: JSON formats are faster than XML
4. Cache Results: Cache SBOM data when possible
5. Batch Operations: Query multiple projects in parallel

Next Steps

• Set up GitHub molecule to link source repositories
• Configure Docker molecule to track container licenses
• Explore software composition analysis workflows