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

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Newer release available (2.23.0)

Owner

PyPI data
Data sourced directly from PyPI's database.

Credits

Author: Gavin M. Roy

License expression

BSD-3-Clause
View SPDX License List

Requires

Python >=3.14

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

imbi_mcp-2.20.0.tar.gz (10.0 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

imbi_mcp-2.20.0-py3-none-any.whl (8.9 kB view details)

Uploaded Python 3

File details

Details for the file imbi_mcp-2.20.0.tar.gz.

File metadata

  • Download URL: imbi_mcp-2.20.0.tar.gz
  • Upload date:
  • Size: 10.0 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for imbi_mcp-2.20.0.tar.gz
Algorithm Hash digest
SHA256 64e1f86251dd6accf777ed2dc7aa6ce763243398da9f20308d369384c1b380bd
MD5 ffddfdf898f6a925f530d038faa5f6e1
BLAKE2b-256 50e26ded41d94981c90cdc9fe8d9411b0c5e7a61cc0ce0156a743bfd3b1a0660

See more details on using hashes here.

Provenance

The following attestation bundles were made for imbi_mcp-2.20.0.tar.gz:

Publisher: release.yml on AWeber-Imbi/imbi

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file imbi_mcp-2.20.0-py3-none-any.whl.

File metadata

  • Download URL: imbi_mcp-2.20.0-py3-none-any.whl
  • Upload date:
  • Size: 8.9 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.14

File hashes

Hashes for imbi_mcp-2.20.0-py3-none-any.whl
Algorithm Hash digest
SHA256 db4219b3f474960270ea3d9e43403eeb170c3fe4a56b9a19759d4ffbbfa2b6d6
MD5 fdee18f9f3a2bb34ffcb0574f34d90ac
BLAKE2b-256 569c197e9d3882da6254c36cf1a6fe20ac952363f488b729ef9921dd1ff27d44

See more details on using hashes here.

Provenance

The following attestation bundles were made for imbi_mcp-2.20.0-py3-none-any.whl:

Publisher: release.yml on AWeber-Imbi/imbi

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page