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.

The server gives MCP clients read-only tools for inspecting Prefect Cloud and self-hosted Prefect instances, plus a docs proxy so assistants can look up current Prefect CLI, SDK, and deployment guidance.

Choose Your Setup

Claude Code Plugin

The easiest local setup for Claude Code is the Prefect plugin:

# 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.

Run Locally

When running the MCP server locally with stdio transport, it automatically uses 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 self-hosted Prefect 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 since this MCP server requires no write permissions.

Deploy Your Own Server

Deploy your own server when you need a custom Prefect API target, self-hosted Prefect, a private network, or an API-key-based team deployment.

1. Fork this repository on GitHub:

   gh repo fork prefecthq/prefect-mcp-server
   

2. Deploy it on Prefect Horizon or FastMCP Cloud.

3. Configure the server:

   • server path: src/prefect_mcp_server/server.py
   • requirements: pyproject.toml
   • environment variables:
     • PREFECT_API_URL: https://api.prefect.cloud/api/accounts/[ACCOUNT_ID]/workspaces/[WORKSPACE_ID]
     • PREFECT_API_KEY: your Prefect Cloud API key
     • PREFECT_API_AUTH_STRING: basic auth credentials for self-hosted Prefect, if needed

4. Add the deployed HTTP URL to your MCP client:

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

[!NOTE] For self-hosted deployments, environment variables are configured on the deployed MCP server, not in your MCP client configuration. The MCP host authenticates access to the MCP server, while this server uses the configured Prefect credentials to access Prefect.

claude mcp add prefect-cloud \
  --transport http https://prefect-cloud-mcp-server.fastmcp.app/mcp