prefect-mcp-server
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).
Deploy on FastMCP Cloud
- Fork this repository on GitHub (
gh repo fork prefecthq/prefect-mcp-server) - Go to fastmcp.cloud and sign in
- 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 (orPREFECT_API_AUTH_STRINGfor OSS with basic auth)
- server path:
- get your server URL (e.g.,
https://your-server-name.fastmcp.app/mcp) - 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
Multi-tenant deployments with HTTP headers
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 keyX-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)
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
Other MCP Clients
Configuration examples
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"
}
}
}
}
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"
}
}
}
}
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
prefectCLI 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
Setup & testing
# 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
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
Metadata
Release files for iflow-mcp_prefecthq-prefect-mcp 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_prefecthq_prefect_mcp-0.1.0.tar.gz | 371.3 kB | Without provenance | Details for iflow_mcp_prefecthq_prefect_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_prefecthq_prefect_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_prefecthq_prefect_mcp-0.1.0-py3-none-any.whl |
Total release size: 406.9 kB
Release files / iflow_mcp_prefecthq_prefect_mcp-0.1.0.tar.gz
| Download URL | iflow_mcp_prefecthq_prefect_mcp-0.1.0.tar.gz |
|---|---|
| Size | 371.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7eca8ec47ce725bb29bf9c15958f17236c5a59dac515aa3499816f80b10e2341
|
|
BLAKE2b-256 checksum How to use checksums |
7b06c95096f7dac33d3427e4b73a3c87d866ff04ac98f82d9da617e09f82c4a4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_prefecthq_prefect_mcp-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_prefecthq_prefect_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 35.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
90de79d07b44ca5052b631eabee1ddb19d439e16964e7eb27bb1ded91f74cdcc
|
|
BLAKE2b-256 checksum How to use checksums |
2af7cc08b9ac2801b797baeadb743de999ebe98f1e1f7bc77d8420d513ef7864
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_prefecthq-prefect-mcp 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.