FOSSA MCP Server

A Model Context Protocol server for the FOSSA API that allows AI assistants to inspect FOSSA organizations and answer practical software composition analysis questions.

Unofficial project. Not affiliated with, endorsed by, or supported by FOSSA, Inc. "FOSSA" is a trademark of FOSSA, Inc., used here only to identify the API this software interoperates with. For the official product and support, see fossa.com.

Safety Statement

Almost every tool is read-only. Four are not.

fossa_enable_security_policy and fossa_assign_security_policy_to_projects change which FOSSA security policy governs a project and whether it blocks builds. fossa_block_package and fossa_unblock_package add and remove blocked-dependency rules on a quality policy. Every other tool only reads.

Writes are off by default. Every write tool refuses before issuing any request unless the operator sets FOSSA_ALLOW_WRITES=true, and fossa_unblock_package additionally requires FOSSA_ALLOW_DESTRUCTIVE=true. Leave them off on any instance that does not need to change FOSSA state — under the single-tenant model below, everyone who reaches this server shares one token and therefore its write access too.

See DECISIONS.md §5 for why the earlier read-only guarantee was dropped, and Write operations for what each tier permits.

Related MCP server: SonarQube MCP Server

Deployment model — single-tenant

This server is designed to be run by one operator with one FOSSA API token. You run your own instance; there is no multi-user mode.

⚠️ The server executes every request using the single FOSSA_API_TOKEN it was started with. It does not authenticate callers or scope requests per user. If you expose the HTTP transport to other people, every one of them gets the full access of that token — including anything it can read across your FOSSA organization.

• stdio is the default transport and the intended deployment shape: your MCP client launches the process, and the token stays local to it.

• streamable-http binds 127.0.0.1 by default and is intended for local or sidecar use. Do not put it on a shared network interface without an authenticating proxy in front of it.

Requirements

• Python 3.13+

• uv

• Full FOSSA API token for live calls

• Node/npm only when launching MCP Inspector through mcp dev

Setup

git clone <repo>
cd fossa-mcp
uv sync
cp .env.example .env

Then edit .env and add your FOSSA API token:

FOSSA_API_TOKEN=<your-full-api-token>

Validate

uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run pyright

pytest never touches the network; the live smoke test is opt-in via uv run pytest -m live and needs a real FOSSA_API_TOKEN.

MCP Inspector

uv run mcp dev src/fossa_mcp/server.py

stdio

uv run fossa-mcp

Streamable HTTP

uv run fossa-mcp --transport streamable-http

Container

docker run --rm -i -e FOSSA_API_TOKEN=<your-full-api-token> rashford/fossa-mcp:0.1

For streamable-http, publish the port and override the default CMD:

docker run --rm -p 8000:8000 -e FOSSA_API_TOKEN=<your-full-api-token> \
  rashford/fossa-mcp:0.1 --transport streamable-http

Images are tagged :0.1.0 and :0.1. :latest is intentionally not published until a release has soaked — see DECISIONS.md.

Every image ships LICENSE, NOTICE, and a consolidated /app/THIRD_PARTY_LICENSES.txt covering every runtime dependency actually installed in that image, generated at build time by scripts/generate_third_party_licenses.py.

Tools

Write operations

Write access is off by default and tiered. Each tier is enabled independently, and the higher ones do not imply the lower: FOSSA_ALLOW_DESTRUCTIVE=true on its own grants nothing, so a half-configured deployment stays safe rather than becoming partly writable.

The gate is checked inside the tool body before any request is constructed, so a refused call sends nothing to FOSSA.

FOSSA_ALLOW_WRITES=true FOSSA_ALLOW_DESTRUCTIVE=true uv run fossa-mcp

Blocking a package

fossa_block_package takes a versionless locator (pip+aiofile, not pip+aiofile$1.2.3) and one or more QUALITY policy ids — a block rule cannot attach to a licensing, security, or SBOM policy. Omit versions to block every version, or pass versions=["3.11.1"] to block only those. Re-blocking is idempotent: FOSSA reuses the existing rule rather than adding a second one.

fossa_unblock_package reverses it, and is gated at the destructive tier for a reason. FOSSA has no delete for a single rule — the only way to remove one is PUT /policies/{id}/rules, which replaces the policy's entire rule set, and the API offers no ETag, If-Match, or version precondition to make that safe. Two callers unblocking different packages at the same time silently clobber each other. The tool reads the policy immediately before writing and reports the surviving rule set it sent in data.rules_sent. If the policy has no matching block rule it changes nothing rather than rewriting the rule set for no reason.

⚠️ Both tools use endpoints FOSSA does not document, captured from its web app's own traffic and verified against the live API. FOSSA owes no stability on them: they can change without notice or a version bump. The contract tests in this repo pin our request shape and cannot detect FOSSA changing its side, so both tools fail loudly rather than degrade quietly if a response stops matching. The verified request schemas are documented in src/fossa_mcp/tools/packages.py and pinned by tests/test_package_tools.py.

Security policies

An assigned security policy (what counts as a violation), security issue scanning (finding violations), and the security status check (failing the build) are what make a vulnerability fail a build. fossa_enable_security_policy sets all three.

That is distinct from blocking a specific package, which is a blacklisted_dependency rule on a quality policy — see Blocking a package. The security policy tools do not block packages by name.

Policies are authored in the FOSSA web app and addressed here by the numeric id in their FOSSA URL. The vendored OpenAPI spec has no create-policy or list-policies operation, though the live API does serve GET /api/policies; no tool wraps it yet.

Local overlay

FOSSA_POLICY_FILE points at a JSON file of local rules layered on top of FOSSA's own findings. The overlay is tighten-only: it can block packages FOSSA currently allows, and it can never clear a package FOSSA has raised an active vulnerability against.

{
  "version": 1,
  "security": [
    {
      "id": "no-high-severity",
      "description": "Stricter than the org-wide FOSSA policy",
      "enabled": true,
      "rules": {
        "max_cvss": 7.0,
        "warn_cvss": 4.0,
        "deny_severity": ["critical"],
        "denied_cves": ["CVE-2025-53365"],
        "denied_packages": ["left-pad", "npm+event-stream"]
      },
      "exceptions": [
        {
          "package": "pip+requests$2.31",
          "reason": "Vendored fork, patch applied out of band",
          "expires": "2026-12-31"
        }
      ]
    }
  ]
}

denied_packages and exceptions[].package accept a full locator (pip+mcp$1.6.0, that version only), a fetcher-qualified name (pip+mcp, any version), or a bare name (mcp, any fetcher).

An exception requires a reason and suppresses only overlay-introduced blocks. Once expires passes it stops applying and is reported on the verdict, so a package never silently reverts to blocked without explanation. A configured-but-unreadable policy file is an error, not a fallback to "no policy".

Turning enforcement on

FOSSA_ALLOW_WRITES=true uv run fossa-mcp

Check what a policy would do before enabling it — fossa_evaluate_security_policy is read-only and answers exactly that.

Example Prompts

List my FOSSA projects sorted by security issues, highest first.

Show active critical and high vulnerabilities for revision <REVISION_LOCATOR>.

Compare revision <NEW_REVISION> with <OLD_REVISION> and show only new vulnerability issues.

Give me the FOSSA risk posture for project <PROJECT_LOCATOR> at revision <REVISION_LOCATOR>.

Generate the Markdown attribution report for revision <REVISION_LOCATOR>.

Which packages in <REVISION_LOCATOR> would my security policy block?

What security policy is <PROJECT_LOCATOR> using, and is the status check on?

Apply security policy 7 to <PROJECT_LOCATOR> and turn on blocking.

Block pip+aiofile on quality policy <POLICY_ID>, every version.

Unblock pip+aiofile on quality policy <POLICY_ID> and show me which rules you kept.

License

Licensed under the Apache License, Version 2.0. See NOTICE for attribution, the trademark disclaimer, and third-party license information.

All runtime dependencies are under permissive licenses (MIT, BSD, Apache-2.0, ISC, PSF) with the exception of certifi, which is MPL-2.0 and is redistributed unmodified.

Container images are built on SUSE Base Container Images, which carry SUSE's own license terms separate from this project's.

Project decisions — including the deliberate mcp version pin and the single-tenant constraint — are recorded in DECISIONS.md.