Ubuntu MCP Servers

MCP servers for querying and submitting Ubuntu data via ubq. Each server exposes a focused set of tools and resources for a single data domain — bugs, packages, versions, or merge requests.

Requirements

• Python >= 3.13
• uv (recommended) or pip

Installation

git clone https://github.com/lvoytek/ubuntu-mcp.git && cd ubuntu-mcp
uv sync

This installs the five entry-point commands:

| Command | Server | |---|---| | ubuntu-mcp-bugs | Bug data | | ubuntu-mcp-packages | Package data | | ubuntu-mcp-versions | Package version data | | ubuntu-mcp-merge-requests | Merge request data | | ubuntu-mcp-all | All of the above at once |

Running a server

All servers share the same CLI flags:

ubuntu-mcp-bugs                                           # streamable-http on 0.0.0.0:8000 (default)
ubuntu-mcp-bugs --transport streamable-http --host 127.0.0.1 --port 9000
ubuntu-mcp-bugs --transport stdio                         # for MCP clients that spawn the process

Replace ubuntu-mcp-bugs with any of the commands above.

Running all servers

Use ubuntu-mcp-all to start every server at once on sequential ports:

ubuntu-mcp-all                              # bugs=8000, packages=8001, versions=8002, merge-requests=8003
ubuntu-mcp-all --host 127.0.0.1 --port 9000 # bugs=9000, packages=9001, versions=9002, merge-requests=9003

Connecting an MCP client

For an HTTP server, add the URL to your client config:

{
  "mcp": {
    "ubuntu-mcp-bugs": {
      "type": "remote",
      "url": "http://127.0.0.1:8000/mcp"
    },
    "ubuntu-mcp-packages": {
      "type": "remote",
      "url": "http://127.0.0.1:8001/mcp"
    },
    "ubuntu-mcp-versions": {
      "type": "remote",
      "url": "http://127.0.0.1:8002/mcp"
    },
    "ubuntu-mcp-merge-requests": {
      "type": "remote",
      "url": "http://127.0.0.1:8003/mcp"
    }
  }
}

For stdio, point the client at the entry-point command directly.

Authentication

Most tools require an authenticated session before they can query data. Call login_provider first.

Launchpad

Launchpad supports three authentication modes:

| Mode | When | |---|---| | Anonymous | No credentials provided — read-only public access. Best for CI or headless environments. | | Credential file | credential_file path points to a file containing a Launchpad OAuth token. | | Inline token | token (and optionally username) passed directly. |

A default credential file path is also checked automatically: ~/.config/ubq/launchpad-credentials. If this file exists and no other credentials are provided, its contents are used as the token.

Anonymous (no credentials)

{
  "tool": "login_provider",
  "arguments": { "provider_name": "launchpad" }
}

Credential file

{
  "tool": "login_provider",
  "arguments": {
    "provider_name": "launchpad",
    "credential_file": "/path/to/launchpad-token"
  }
}

Inline token

{
  "tool": "login_provider",
  "arguments": {
    "provider_name": "launchpad",
    "token": "oauth-token-value"
  }
}

GitHub

GitHub requires a personal access token passed via token:

{
  "tool": "login_provider",
  "arguments": {
    "provider_name": "github",
    "token": "ghp_xxxxxxxxxxxx"
  }
}

Snapcraft

Snapcraft requires a token passed via token:

{
  "tool": "login_provider",
  "arguments": {
    "provider_name": "snapcraft",
    "token": "snap-token-value"
  }
}

Servers and tools

Bugs — ubuntu-mcp-bugs

| Tool | Description | |---|---| | login_provider | Authenticate with a bug data provider | | list_bug_providers | List available bug data provider names | | get_bug | Fetch a bug by ID | | search_bugs | Search bugs by criteria | | submit_bug | Submit a new bug |

Resources:

• ubq://bugs/providers — available bug data providers
• ubq://bugs/sessions — active bug data provider sessions

get_bug

bug_id: str          — the bug ID
provider_name: str   — e.g. "launchpad" or "github"
metadata_only: bool  — set True to skip comments and tasks

search_bugs

provider_name: str          — e.g. "launchpad" or "github"
title: str | None           — filter by title substring
tags: list[str] | None      — filter by tags
status: str | None          — e.g. "New", "Fix Released"
importance: str | None      — e.g. "Medium", "High"
owner: str | None           — username of the bug owner
assignee: str | None        — username of the assignee
milestone: str | None       — milestone name
created_since: str | None   — ISO 8601 date (e.g. "2025-01-01")
created_before: str | None  — ISO 8601 date
modified_since: str | None  — ISO 8601 date

submit_bug

title: str                  — bug title (required)
provider_name: str          — e.g. "launchpad" or "github"
package_names: list[str]    — affected package names
description: str | None     — bug description
importance: str | None      — e.g. "Medium"
status: str | None          — e.g. "New"
tags: list[str] | None      — tags to apply
assignee: str | None        — username to assign
private: bool               — mark the bug private (default False)
milestone: str | None       — target milestone

Packages — ubuntu-mcp-packages

| Tool | Description | |---|---| | login_provider | Authenticate with a package data provider | | list_package_providers | List available package data provider names | | get_package | Fetch a package by name |

Resources:

• ubq://packages/providers — available package data providers
• ubq://packages/sessions — active package data provider sessions

get_package

package_name: str    — the source package name
provider_name: str   — e.g. "launchpad" or "snapcraft"

Versions — ubuntu-mcp-versions

| Tool | Description | |---|---| | login_provider | Authenticate with a version data provider | | list_version_providers | List available version data provider names | | get_version | Fetch the version of a package in an Ubuntu series |

Resources:

• ubq://versions/providers — available version data providers
• ubq://versions/sessions — active version data provider sessions

get_version

package_name: str    — the source package name
series: str          — Ubuntu codename (e.g. "noble", "jammy")
provider_name: str   — e.g. "launchpad" or "snapcraft"
pocket: str | None   — "Release", "Security", "Updates", "Proposed", or None for default

Merge Requests — ubuntu-mcp-merge-requests

| Tool | Description | |---|---| | login_provider | Authenticate with a merge request provider | | list_merge_request_providers | List available merge request provider names | | get_merge_request | Fetch a merge request by ID | | get_merge_requests_from_user | Fetch merge requests assigned to a user |

Resources:

• ubq://merge-requests/providers — available merge request providers
• ubq://merge-requests/sessions — active merge request provider sessions

get_merge_request

merge_request_id: str  — the merge request ID
provider_name: str     — e.g. "launchpad" or "github"

get_merge_requests_from_user

user_id: str         — username
provider_name: str    — e.g. "launchpad" or "github"

Available providers

| Provider | Domains | |---|---| | launchpad | Bugs, packages, versions, merge requests | | github | Bugs, merge requests | | snapcraft | Packages, versions |

Development

uv sync                    # install all dependencies
uv run ruff check .         # lint
uv run pytest tests/ -v    # run tests

License

GPL-3.0