prefect

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.

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"
  }
}'

{
  "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"
      }
    }
  }
}

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)

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