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 --
GETendpoints that return collections. - Resource templates --
GETendpoints 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
Authorizationheader — an Imbiik_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-urland--auth-server-url(see below) to make the server an OAuth 2.0 Resource Server. It then verifies JWT access tokens locally, accepts-and-forwardsik_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 sharedIMBI_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
Logging
HTTP transports log through imbi-common: one access-log record per
request on imbi.mcp.access, in the shared format, with the
authenticated principal and the invoked tool name.
2026-08-21T19:12:02.734 INFO imbi.mcp.access: 10.32.132.108:0 - gavinr "POST /mcp HTTP/1.1" 200 (tool:list_projects)
Uvicorn's own access log is disabled so lines are not duplicated.
Successful /status probes are not logged; failures still are.
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.35.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| imbi_mcp-2.35.1.tar.gz | 11.2 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| imbi_mcp-2.35.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 20.7 kB
Release files / imbi_mcp-2.35.1.tar.gz
| Download URL | imbi_mcp-2.35.1.tar.gz |
|---|---|
| Size | 11.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0e7b5f462157cd1bdb0461db4a48426dfe8509720eced2d7c5ea78ef2db3c1b6
|
|
BLAKE2b-256 checksum How to use checksums |
beb7f2af8c6d3fb8eada35c6a29e8b646b1c3698a656b11bd16a35d816d2e101
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency logRelease files / imbi_mcp-2.35.1-py3-none-any.whl
| Download URL | imbi_mcp-2.35.1-py3-none-any.whl |
|---|---|
| Size | 9.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
89bbf4e24e31f0324910313f9626b864e785afd5e489e2451a6ad65e26f418a8
|
|
BLAKE2b-256 checksum How to use checksums |
39646cd18f6878e4d31c22b57f7a6883bbbe8ea6bc9c889aabf1bc0c4284314e
|
| Upload date | |
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 23, 2026.
Transparency log
