prefect-mcp-server

[!WARNING] This project is under active development and may change drastically at any time.

This is an experimental MCP server for Prefect. APIs, features, and behaviors are subject to change without notice. We encourage you to try it out, provide feedback, and contribute! Please create issues or open PRs with your ideas and suggestions.

An MCP server for interacting with prefect resources.

Quick start

Claude Code plugin (recommended)

The easiest way to get started with Claude Code:

# add from marketplace
/plugin marketplace add prefecthq/prefect-mcp-server

# install the plugin
/plugin install prefect

This installs both the MCP server (for read-only diagnostics) and a CLI skill (for mutations like triggering deployments or cancelling runs).

[!NOTE] The plugin uses your local Prefect configuration from ~/.prefect/profiles.toml. For explicit credentials, use the local uvx setup below.

Deploy on FastMCP Cloud

1. Fork this repository on GitHub (gh repo fork prefecthq/prefect-mcp-server)
2. Go to fastmcp.cloud and sign in
3. Create a new server pointing to your fork:
   • server path: src/prefect_mcp_server/server.py
   • requirements: pyproject.toml (or leave blank)
   • environment variables:
     • PREFECT_API_URL: https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID]
     • PREFECT_API_KEY: your Prefect Cloud API key (or PREFECT_API_AUTH_STRING for OSS with basic auth)
4. get your server URL (e.g., https://your-server-name.fastmcp.app/mcp)
5. Add to your favorite MCP client (e.g., Claude Code):

# add to claude code with http transport
claude mcp add prefect --transport http https://your-server-name.fastmcp.app/mcp

[!NOTE] When deploying to FastMCP Cloud, environment variables are configured on the FastMCP Cloud server itself, not in your client configuration. FastMCP's authentication secures access to your MCP server, while the MCP server uses your Prefect API key to access your Prefect instance.

<details> <summary>Multi-tenant deployments with HTTP headers</summary>

For centrally-hosted deployments where multiple users connect to the same MCP server instance, credentials can be passed via HTTP headers instead of environment variables. This enables each user to authenticate with their own Prefect workspace.

Supported headers:

• X-Prefect-Api-Url: Prefect API URL (required for both Cloud and OSS)
• X-Prefect-Api-Key: Prefect Cloud API key
• X-Prefect-Api-Auth-String: Basic auth credentials for OSS (format: username:password)

Claude Code CLI:

claude mcp add-json prefect '{
  "type": "http",
  "url": "https://your-server.fastmcp.app/mcp",
  "headers": {
    "X-Prefect-Api-Url": "https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID]",
    "X-Prefect-Api-Key": "your-api-key"
  }
}'

Claude Desktop app:

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "prefect": {
      "type": "http",
      "url": "https://your-server.fastmcp.app/mcp",
      "headers": {
        "X-Prefect-Api-Url": "https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID]",
        "X-Prefect-Api-Key": "your-api-key"
      }
    }
  }
}

Python with FastMCP client:

from fastmcp.client import Client
from fastmcp.client.transports import StreamableHttpTransport

headers = {
    "X-Prefect-Api-Url": "https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID]",
    "X-Prefect-Api-Key": "your-api-key",
}

transport = StreamableHttpTransport(url="https://your-server.fastmcp.app/mcp", headers=headers)
client = Client(transport=transport)

async with client:
    result = await client.call_tool("get_identity", {})
    print(result)

[!TIP] Find your Prefect Cloud credentials in your dashboard or in ~/.prefect/profiles.toml

[!NOTE] When HTTP headers are provided, they take precedence over environment variables. If no headers are present, the server falls back to using the configured environment variables.

</details>

run locally

When running the MCP server locally (via stdio transport), it will automatically use your local Prefect configuration from ~/.prefect/profiles.toml if available.

# minimal setup - inherits from local prefect profile
claude mcp add prefect \
  -- uvx --from prefect-mcp prefect-mcp-server

# or explicitly set credentials
claude mcp add prefect \
  -e PREFECT_API_URL=https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID] \
  -e PREFECT_API_KEY=your-cloud-api-key \
  -- uvx --from prefect-mcp prefect-mcp-server

[!NOTE] For open-source servers with basic auth, use PREFECT_API_AUTH_STRING instead of PREFECT_API_KEY

[!TIP] Prefect Cloud users on Team, Pro, and Enterprise plans can use service accounts for API authentication. Pro and Enterprise users can restrict service accounts to read-only access (only see_* permissions) since this MCP server requires no write permissions.

Other MCP Clients

<details> <summary>Configuration examples</summary>

This MCP server works with any MCP-compatible client. Here are configuration examples for popular clients:

Cursor

Add to your Cursor settings (.cursor/mcp.json):

{
  "mcpServers": {
    "prefect": {
      "command": "uvx",
      "args": ["--from", "prefect-mcp", "prefect-mcp-server"],
      "env": {
        "PREFECT_API_URL": "https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID]",
        "PREFECT_API_KEY": "your-api-key"
      }
    }
  }
}

Codex CLI

Add using the Codex CLI:

# minimal setup - inherits from local prefect profile
codex mcp add prefect -- uvx --from prefect-mcp prefect-mcp-server

# with explicit credentials
codex mcp add prefect \
  --env PREFECT_API_URL=https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID] \
  --env PREFECT_API_KEY=your-api-key \
  -- uvx --from prefect-mcp prefect-mcp-server

Or edit ~/.codex/config.toml directly:

[mcp.prefect]
command = "uvx"
args = ["--from", "prefect-mcp", "prefect-mcp-server"]

[mcp.prefect.env]
PREFECT_API_URL = "https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID]"
PREFECT_API_KEY = "your-api-key"

Gemini CLI

Add using the Gemini CLI:

# minimal setup - inherits from local prefect profile
gemini mcp add prefect uvx --from prefect-mcp prefect-mcp-server

# with explicit credentials
gemini mcp add prefect \
  -e PREFECT_API_URL=https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID] \
  -e PREFECT_API_KEY=your-api-key \
  uvx --from prefect-mcp prefect-mcp-server

# HTTP transport - for FastMCP Cloud deployment
gemini mcp add prefect --transport http https://your-server-name.fastmcp.app/mcp

Or edit ~/.gemini/settings.json directly:

{
  "mcpServers": {
    "prefect": {
      "command": "uvx",
      "args": ["--from", "prefect-mcp", "prefect-mcp-server"],
      "env": {
        "PREFECT_API_URL": "https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID]",
        "PREFECT_API_KEY": "your-api-key"
      }
    }
  }
}

Kiro

Add to your Kiro MCP settings (~/.kiro/settings/mcp.json):

{
  "mcpServers": {
    "prefect": {
      "command": "uvx",
      "args": ["--from", "prefect-mcp", "prefect-mcp-server"],
      "env": {
        "PREFECT_API_URL": "https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID]",
        "PREFECT_API_KEY": "your-api-key"
      }
    }
  }
}

VS Code with GitHub Copilot

Add to your VS Code settings (.vscode/mcp.json):

{
  "servers": {
    "prefect": {
      "command": "uvx",
      "args": ["--from", "prefect-mcp", "prefect-mcp-server"],
      "env": {
        "PREFECT_API_URL": "https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID]",
        "PREFECT_API_KEY": "your-api-key"
      }
    }
  }
}

Windsurf

Add to your Windsurf MCP config (~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "prefect": {
      "command": "uvx",
      "args": ["--from", "prefect-mcp", "prefect-mcp-server"],
      "env": {
        "PREFECT_API_URL": "https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID]",
        "PREFECT_API_KEY": "your-api-key"
      }
    }
  }
}

[!TIP] Most MCP clients follow a similar configuration pattern. If your client isn't listed here, check its documentation for MCP server configuration - the command, args, and env values above should work with minor adjustments to the config format.

</details>

Capabilities

This server enables MCP clients like Claude Code to interact with your Prefect instance:

Monitoring & inspection

• View dashboard overviews with flow run statistics and work pool status
• Query deployments, flow runs, task runs, and work pools with advanced filtering
• Retrieve detailed execution logs from flow runs
• Track events across your workflow ecosystem

Enable CLI usage

• Allows AI assistants to effectively use the prefect CLI to manage Prefect resources
• Create automations, trigger deployment runs, and more while maintaining proper attribution

Intelligent debugging

• Get contextual guidance for troubleshooting failed flow runs
• Diagnose deployment issues, including concurrency problems
• Identify root causes of workflow failures

Development

<details> <summary>Setup & testing</summary>

# clone the repo
gh repo clone prefecthq/prefect-mcp-server && cd prefect-mcp-server

# install dev deps and pre-commit hooks
just setup

# run tests (uses ephemeral prefect database via prefect_test_harness)
just test

</details>

Links

• FastMCP - the easiest way to build an mcp server
• FastMCP Cloud - deploy your MCP server to the cloud
• Prefect - the easiest way to build workflows
• Claude Code - one of the best MCP clients

---

mcp-name: io.github.PrefectHQ/prefect-mcp-server