imbi-mcp

MCP server for the Imbi DevOps service management platform. Exposes Imbi API functionality to AI agents via the Model Context Protocol.

How It Works

At startup the server fetches the OpenAPI spec from a running imbi-api instance and auto-generates MCP tools, resources, and resource templates using FastMCP.

Route mapping rules control what gets exposed:

Excluded -- Auth, MFA, status, and thumbnail endpoints are hidden.
Resources -- GET endpoints that return collections.
Resource templates -- GET endpoints with path parameters.
Tools -- Everything else (create, update, delete operations).

The caller's Authorization header is forwarded to the API so that requests run with the caller's permissions.

Authentication

Two modes, which can be used together:

Token (always on). The caller's Authorization header — an Imbi ik_ API key or a JWT — is forwarded to the API, which authorizes the request. This works with no extra configuration.
OAuth (when configured). Set --public-url and --auth-server-url (see below) to make the server an OAuth 2.0 Resource Server. It then verifies JWT access tokens locally, accepts-and-forwards ik_ API keys, and publishes Protected Resource Metadata so MCP clients can discover the Imbi authorization server and run a browser login flow (authorization-code + PKCE, with Dynamic Client Registration). Local JWT verification uses the shared IMBI_AUTH_JWT_SECRET.

FastMCP's DNS-rebinding Host/Origin guard is opt-in (disabled by default as of fastmcp 3.4.4), so requests arriving through a reverse proxy are accepted normally. To enable it, set FASTMCP_HTTP_HOST_ORIGIN_PROTECTION=true and list the public host(s) in FASTMCP_HTTP_ALLOWED_HOSTS='["your-host"]'.

Requirements

Python 3.12+
A running imbi-api instance

Quick Start

# Install dependencies
moon run root:setup

# Run the server (imbi-api must be reachable)
uv run imbi-mcp serve

# Or with explicit options
uv run imbi-mcp serve --api-url http://localhost:8000 --transport streamable-http

CLI Options

imbi-mcp serve [OPTIONS]

Option	Default	Env Var	Description
`--api-url`	`http://localhost:8000`	`IMBI_INTERNAL_API_URL`	Base URL of the Imbi API
`--transport`	`streamable-http`		MCP transport type
`--host`	`127.0.0.1`		Host to bind to
`--port`	`8001`		Port to bind to
`--public-url`	(none)	`IMBI_MCP_PUBLIC_URL`	Public base URL of the host fronting this server, WITHOUT the `/mcp` path (e.g. `https://host`); FastMCP appends its own `/mcp` mount path. Enables OAuth with `--auth-server-url`
`--auth-server-url`	(none)	`IMBI_MCP_AUTH_SERVER_URL`	Imbi OAuth issuer URL (e.g. `https://host`); enables OAuth with `--public-url`

Supported transports: stdio, http, sse, streamable-http

Docker

docker build -t imbi-mcp .
docker run -p 8001:8001 -e IMBI_INTERNAL_API_URL=http://imbi-api:8000 imbi-mcp

Development

moon run root:setup                         # Install deps and pre-commit hooks
moon run mcp:test                           # Run tests (90% coverage minimum)
moon run mcp:lint mcp:typecheck mcp:format  # Run ruff + basedpyright + format check
uv run pre-commit run --all-files           # Auto-format code

License

BSD-3-Clause

Release files for imbi-mcp 2.26.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for imbi-mcp 2.26.1
File	Size	Uploaded
imbi_mcp-2.26.1.tar.gz	10.1 kB	Aug 20, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for imbi-mcp 2.26.1
File	Interpreter	ABI	Platform	Reset
imbi_mcp-2.26.1-py3-none-any.whl 8.9 kB Aug 20, 2026	Python 3	none	any	Details

Total release size: 19.0 kB

Release files / imbi_mcp-2.26.1.tar.gz

Download URL	imbi_mcp-2.26.1.tar.gz
Size	10.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`632a3d6270a9bf7e6fae8ad954cfc07470d4002698d313d6e91c8880d6049a17`
BLAKE2b-256 checksum How to use checksums	`aa27b24195b85be8e93a9e9c6880f75b5f8491b67398bb828d1a3d4721360e8a`
Upload date	Aug 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

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.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/AWeber-Imbi/imbi
Publishing commit: github.com/AWeber-Imbi/imbi/tree/364a24451047b43763b4aa1b2069d2b1f03ca5b4

Workflow

Publishing configuration: github.com/AWeber-Imbi/imbi/blob/364a24451047b43763b4aa1b2069d2b1f03ca5b4/.github/workflows/release.yml
Publishing logs: github.com/AWeber-Imbi/imbi/actions/runs/32331765161/attempts/1

Artifact

Subject: imbi_mcp-2.26.1.tar.gz
SHA-256 checksum: 632a3d6270a9bf7e6fae8ad954cfc07470d4002698d313d6e91c8880d6049a17 Verifying attestations

Release files / imbi_mcp-2.26.1-py3-none-any.whl

Download URL	imbi_mcp-2.26.1-py3-none-any.whl
Size	8.9 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`0c68f3746802f91a6f962681c2515873f821df77ae73ae444992415c041940d3`
BLAKE2b-256 checksum How to use checksums	`de30aca517195d2883d839d02f6c60e3f074423d0d05398286c763648a97fcc0`
Upload date	Aug 20, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/AWeber-Imbi/imbi
Publishing commit: github.com/AWeber-Imbi/imbi/tree/364a24451047b43763b4aa1b2069d2b1f03ca5b4

Workflow

Publishing configuration: github.com/AWeber-Imbi/imbi/blob/364a24451047b43763b4aa1b2069d2b1f03ca5b4/.github/workflows/release.yml
Publishing logs: github.com/AWeber-Imbi/imbi/actions/runs/32331765161/attempts/1

Artifact

Subject: imbi_mcp-2.26.1-py3-none-any.whl
SHA-256 checksum: 0c68f3746802f91a6f962681c2515873f821df77ae73ae444992415c041940d3 Verifying attestations