JFrog

Read-only Model Context Protocol server for JFrog Artifactory repository intelligence.

This server is intentionally narrow. It lists repositories, lists explicit repository paths, fetches item metadata, fetches properties and stats, and performs bounded file searches. It does not deploy, delete, move, copy, mutate properties, run raw AQL, or download file content.

It is intended for MCP-compatible agents and clients that need safe Artifactory visibility without artifact download or repository mutation permissions.

Tools

• jfrog_ping checks URL and token access without returning secrets.
• jfrog_capabilities describes server limits, security settings, compatibility behavior, and optional live feature probes for a repo/path.
• jfrog_list_repositories lists repositories with optional type, package_type, and project filters.
• jfrog_list_path lists one repository path with bounded depth and cursor pagination. If Artifactory rejects the Pro-only storage list mode, it falls back to basic metadata children.
• jfrog_get_item_info returns metadata for one file or folder.
• jfrog_get_item_properties returns item properties as a separate storage query mode.
• jfrog_get_item_stats returns download statistics as a separate storage query mode.
• jfrog_get_tree returns a bounded file/folder tree using metadata traversal.
• jfrog_find_files searches files with generic filters and response shaping.
• jfrog_latest_files searches files and sorts the bounded result set by modified client-side.

The safe search tools intentionally avoid non-portable AQL fields and default server-side sorting, because some Artifactory OSS/CE installations reject those features. Use name_pattern for artifact-specific needs, such as *.jar, *.war, or *.zip, instead of adding artifact-specific tools.

All tools are annotated as read-only and non-destructive for MCP clients that use tool safety metadata.

Resources

• jfrog://repositories lists repositories.
• jfrog://repo/{repoKey} lists the root path of one repository.
• jfrog://repo/{repoKey}/path/{path} returns metadata for one repository path. Encode slashes in path as %2F, for example jfrog://repo/libs-release-local/path/com%2Facme.

Requirements

• Python 3.11 or newer.
• A JFrog Artifactory URL.
• A least-privilege read-only JFrog access token.
• Optional: Node.js 18 or newer if you use the npx wrapper.

Configuration

Set credentials through a local .env file, environment variables, or a mounted token file. Do not pass the token as a tool argument.

For local use, copy the template and edit the values:

Copy-Item .env.example .env
notepad .env

Minimal .env with a direct token:

JFROG_URL=https://example.jfrog.io
JFROG_ACCESS_TOKEN=REPLACE_ME

Or use a token file:

New-Item -ItemType Directory -Force .secrets
Set-Content -NoNewline .secrets/jfrog-token "REPLACE_ME"

JFROG_URL=https://example.jfrog.io
JFROG_ACCESS_TOKEN_FILE=.secrets/jfrog-token

JFROG_ACCESS_TOKEN takes priority when both settings are present. Direct tokens are convenient for local agents and private runtime configuration. Token files are still useful for mounted secrets in containers, CI, Kubernetes, and OpenShift.

export JFROG_URL="https://example.jfrog.io"
export JFROG_ACCESS_TOKEN="REPLACE_ME"

Optional settings:

export JFROG_MCP_TRANSPORT="stdio"
export JFROG_REQUEST_TIMEOUT_SECONDS="20"
export JFROG_DEFAULT_PAGE_SIZE="50"
export JFROG_MAX_PAGE_SIZE="200"
export JFROG_MAX_DEPTH="5"
export JFROG_MAX_AQL_LIMIT="500"
export JFROG_CACHE_TTL_SECONDS="60"
export JFROG_VERIFY_SSL="true"
export JFROG_CA_BUNDLE="/etc/ssl/certs/company-ca.pem"
export JFROG_TRUST_ENV="false"
export JFROG_LOG_LEVEL="INFO"

JFROG_URL may be either the JFrog base URL, such as https://example.jfrog.io, or the Artifactory base URL, such as https://example.jfrog.io/artifactory.

Keep JFROG_VERIFY_SSL=true in production. If your Artifactory endpoint uses a private CA, set JFROG_CA_BUNDLE to the mounted PEM bundle instead of disabling verification.

JFROG_TRUST_ENV=false makes the HTTP client ignore proxy-related environment variables. Keep this default for internal Artifactory routes unless your deployment intentionally needs HTTP_PROXY or HTTPS_PROXY.

Install And Run

Clone the repository and install the Python package in a virtual environment:

git clone https://github.com/mSaeedS/jfrog-mcp.git
cd jfrog-mcp
python -m venv .venv
. .venv/bin/activate
pip install -e .
jfrog-mcp

For Windows PowerShell:

git clone https://github.com/mSaeedS/jfrog-mcp.git
Set-Location jfrog-mcp
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -e .
jfrog-mcp

The default transport is stdio. For Streamable HTTP:

JFROG_MCP_TRANSPORT=streamable-http jfrog-mcp

MCP Client Examples

Installed Python Command

If jfrog-mcp is installed in the environment where your MCP client runs:

{
  "mcpServers": {
    "jfrog": {
      "command": "jfrog-mcp",
      "env": {
        "JFROG_URL": "https://example.jfrog.io",
        "JFROG_ACCESS_TOKEN": "REPLACE_ME"
      }
    }
  }
}

Local Clone

If your MCP client can start a command from a local clone:

{
  "mcpServers": {
    "jfrog": {
      "command": "python",
      "args": [
        "-m",
        "jfrog_mcp"
      ],
      "cwd": "/path/to/jfrog-mcp",
      "env": {
        "JFROG_URL": "https://example.jfrog.io",
        "JFROG_ACCESS_TOKEN": "REPLACE_ME",
        "JFROG_TRUST_ENV": "false"
      }
    }
  }
}

On Windows, use a Windows path for cwd, for example C:\\Users\\you\\src\\jfrog-mcp.

npx From GitHub

For agents that expect an npx-style MCP command, use the included Node wrapper. The wrapper starts the Python MCP server, sets JFROG_ENV_FILE to the project .env when present, and preserves stdio for MCP protocol traffic.

Using this public GitHub repository:

{
  "mcpServers": {
    "jfrog": {
      "command": "npx",
      "args": [
        "-y",
        "github:mSaeedS/jfrog-mcp"
      ],
      "env": {
        "JFROG_URL": "https://example.jfrog.io",
        "JFROG_ACCESS_TOKEN": "REPLACE_ME",
        "JFROG_TRUST_ENV": "false"
      }
    }
  }
}

For GitHub npx usage, the wrapper bootstraps a small Python virtual environment in the user cache on first run and installs the bundled Python package there. If your environment uses an internal Python package index, pass PIP_INDEX_URL or PIP_EXTRA_INDEX_URL through the MCP env.

If Windows, OneDrive, or another synced folder blocks the default npm cache, set a cache outside synced folders before running npx:

$env:npm_config_cache = "$env:TEMP\npm-cache"
npx -y "github:mSaeedS/jfrog-mcp" --version

Docker

docker build -t jfrog-mcp:latest .
docker run --rm -i \
  -e JFROG_URL="https://example.jfrog.io" \
  -e JFROG_ACCESS_TOKEN="REPLACE_ME" \
  jfrog-mcp:latest

For HTTP transport:

docker run --rm -p 8000:8000 \
  -e JFROG_URL="https://example.jfrog.io" \
  -e JFROG_ACCESS_TOKEN="REPLACE_ME" \
  -e JFROG_MCP_TRANSPORT="streamable-http" \
  jfrog-mcp:latest

Production Notes

• Use a least-privilege read-only JFrog access token. Rotate it regularly and immediately after any accidental exposure.
• Use JFROG_ACCESS_TOKEN when your agent/runtime can inject secrets securely as environment variables. Use JFROG_ACCESS_TOKEN_FILE when your platform mounts secrets as files.
• Set page, depth, and AQL limits for your environment with JFROG_MAX_PAGE_SIZE, JFROG_MAX_DEPTH, and JFROG_MAX_AQL_LIMIT.
• Run jfrog_capabilities(live_probe=true, repo_key="...", path="...") against a representative repo to discover whether that Artifactory instance supports Pro storage listing or server-side AQL sort.
• Restart the MCP client or server process after changing environment variables or code. Existing stdio MCP sessions keep their original process environment.
• Treat JFROG_VERIFY_SSL=false as local troubleshooting only. Use JFROG_CA_BUNDLE for private CA deployments.

Tests

Install the development dependencies before running tests:

pip install -e ".[dev]"

python -m pytest

The tests use mocked HTTP transports and do not call a real JFrog instance.

Optional live tests run only when all of these are set:

export JFROG_TEST_URL="https://example.jfrog.io"
export JFROG_TEST_TOKEN="REPLACE_ME"
export JFROG_TEST_REPO="libs-release-local"
pytest tests/test_live_integration.py