overseerr-mcp 1.0.1__tar.gz

overseerr_mcp-1.0.1/.agents/plugins/marketplace.json

@@ -0,0 +1,20 @@
+{
+  "name": "overseerr-mcp",
+  "interface": {
+    "displayName": "Overseerr MCP"
+  },
+  "plugins": [
+    {
+      "name": "overseerr-mcp",
+      "source": {
+        "source": "local",
+        "path": "./"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Media"
+    }
+  ]
+}

overseerr_mcp-1.0.1/.app.json

@@ -0,0 +1 @@
+{"name": "overseerr-mcp", "version": "1.0.0", "description": "Overseerr media request management via MCP"}

overseerr_mcp-1.0.1/.claude-plugin/plugin.json

@@ -0,0 +1,45 @@
+{
+  "name": "overseerr-mcp",
+  "version": "1.0.1",
+  "description": "Overseerr media requests via MCP tools with HTTP fallback. Search movies and TV shows, submit requests, and monitor failed requests.",
+  "author": {
+    "name": "Jacob Magar"
+  },
+  "homepage": "https://github.com/jmagar/overseerr-mcp",
+  "repository": "https://github.com/jmagar/overseerr-mcp",
+  "license": "MIT",
+  "keywords": [
+    "overseerr",
+    "media",
+    "requests",
+    "plex",
+    "mcp"
+  ],
+  "userConfig": {
+    "overseerr_mcp_url": {
+      "type": "string",
+      "title": "Overseerr MCP Server URL",
+      "description": "URL of the overseerr-mcp MCP server (e.g. http://overseerr-mcp:9151).",
+      "default": "https://overseerr.tootie.tv/mcp",
+      "sensitive": false
+    },
+    "overseerr_mcp_token": {
+      "type": "string",
+      "title": "MCP Server Bearer Token",
+      "description": "Bearer token for authenticating with the MCP server. Must match OVERSEERR_MCP_TOKEN in the server's .env. Generate with: openssl rand -hex 32",
+      "sensitive": true
+    },
+    "overseerr_url": {
+      "type": "string",
+      "title": "Overseerr Server URL",
+      "description": "Base URL of your Overseerr server, e.g. https://overseerr.example.com. No trailing slash.",
+      "sensitive": true
+    },
+    "overseerr_api_key": {
+      "type": "string",
+      "title": "Overseerr API Key",
+      "description": "Overseerr API key. Found in Overseerr Settings → General → API Key.",
+      "sensitive": true
+    }
+  }
+}

overseerr_mcp-1.0.1/.codex-plugin/plugin.json

@@ -0,0 +1,43 @@
+{
+  "name": "overseerr-mcp",
+  "version": "1.0.1",
+  "description": "Overseerr media requests via MCP.",
+  "homepage": "https://github.com/jmagar/overseerr-mcp",
+  "repository": "https://github.com/jmagar/overseerr-mcp",
+  "license": "MIT",
+  "keywords": [
+    "overseerr",
+    "media",
+    "requests",
+    "plex",
+    "mcp"
+  ],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "apps": "./.app.json",
+  "interface": {
+    "displayName": "Overseerr MCP",
+    "shortDescription": "Search media and submit Overseerr requests",
+    "longDescription": "Search movies and TV shows, inspect details, and submit or review Overseerr media requests through MCP tools and bundled skills.",
+    "developerName": "Jacob Magar",
+    "category": "Media",
+    "capabilities": [
+      "Read",
+      "Write"
+    ],
+    "websiteURL": "https://github.com/jmagar/overseerr-mcp",
+    "defaultPrompt": [
+      "Search Overseerr for a movie.",
+      "Request a TV show in Overseerr.",
+      "Check failed Overseerr requests."
+    ],
+    "brandColor": "#F59E0B",
+    "composerIcon": "./assets/icon.png",
+    "logo": "./assets/logo.svg"
+  },
+  "author": {
+    "name": "Jacob Magar",
+    "email": "jmagar@users.noreply.github.com",
+    "url": "https://github.com/jmagar"
+  }
+}

overseerr_mcp-1.0.1/.dockerignore

@@ -0,0 +1,49 @@
+.git
+.github
+.claude-plugin
+.codex-plugin
+.agents
+.beads
+.dolt
+.omc
+.lavra
+.serena
+.cache
+.worktrees
+.full-review
+.full-review-archive-*
+.vscode
+.cursor
+.windsurf
+.1code
+.idea
+.env
+.env.*
+!.env.example
+*.log
+logs/
+backups/
+docs/
+specs/
+*.md
+!README.md
+__pycache__
+*.pyc
+.pytest_cache
+.ruff_cache
+.mypy_cache
+.coverage
+htmlcov
+.hypothesis
+node_modules
+dist
+coverage
+*.tsbuildinfo
+target
+Justfile
+biome.json
+.pre-commit-config.yaml
+.prettierrc
+.prettierignore
+tests/
+

overseerr_mcp-1.0.1/.env.example

@@ -0,0 +1,47 @@
+# Overseerr MCP Server Environment Configuration
+
+# =============================================================================
+# OVERSEERR CONNECTION
+# =============================================================================
+OVERSEERR_URL=https://your-overseerr-instance.example.com
+OVERSEERR_API_KEY=your_overseerr_api_key
+
+# =============================================================================
+# MCP SERVER SETTINGS
+# =============================================================================
+
+# Bearer token for MCP server authentication (required unless OVERSEERR_MCP_NO_AUTH=true)
+# Generate with: openssl rand -hex 32
+OVERSEERR_MCP_TOKEN=
+
+# Set to true to disable bearer auth (only if secured at network/proxy level)
+OVERSEERR_MCP_NO_AUTH=false
+
+# Transport mode: 'http' for HTTP server
+OVERSEERR_MCP_TRANSPORT=http
+
+# Host interface (0.0.0.0 for Docker/external access)
+OVERSEERR_MCP_HOST=0.0.0.0
+
+# Port the MCP server binds to (update compose port mappings if changed)
+OVERSEERR_MCP_PORT=9151
+
+# =============================================================================
+# DESTRUCTIVE OPERATION GATES
+# =============================================================================
+OVERSEERR_MCP_ALLOW_DESTRUCTIVE=false
+OVERSEERR_MCP_ALLOW_YOLO=false
+
+# =============================================================================
+# DOCKER / COMPOSE
+# =============================================================================
+PUID=1000
+PGID=1000
+DOCKER_NETWORK=mcp-net
+APPDATA_PATH=/mnt/appdata
+
+# =============================================================================
+# LOGGING
+# =============================================================================
+OVERSEERR_LOG_LEVEL=INFO
+LOG_LEVEL=INFO

overseerr_mcp-1.0.1/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: uv sync --group dev
+      - name: Ruff check
+        run: uv run ruff check .
+      - name: Ruff format
+        run: uv run ruff format --check .
+  typecheck:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: uv sync --group dev
+      - run: uv run ty check
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Install dependencies
+        run: uv sync --group dev
+      - run: uv run pytest
+  version-sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: bash scripts/check-outdated-deps.sh || true
+  contract-drift:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: bash scripts/lint-plugin.sh

overseerr_mcp-1.0.1/.github/workflows/docker-publish.yml

@@ -0,0 +1,75 @@
+name: Build and Push Docker Image
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - 'v*'
+  pull_request:
+    branches:
+      - main
+  workflow_dispatch:
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build-and-push:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
+
+      - name: Log in to GitHub Container Registry
+        if: github.event_name != 'pull_request'
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9 # v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract metadata
+        id: meta
+        uses: docker/metadata-action@c299e40c65443455700f0fdfc63efafe5b349051 # v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+          tags: |
+            type=ref,event=branch
+            type=ref,event=pr
+            type=semver,pattern={{version}}
+            type=semver,pattern={{major}}.{{minor}}
+            type=semver,pattern={{major}}
+            type=raw,value=latest,enable={{is_default_branch}}
+            type=sha
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@ca052bb54ab0790a636c9b5f226502c73d547a25 # v5
+        with:
+          context: .
+          platforms: linux/amd64,linux/arm64
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          labels: ${{ steps.meta.outputs.labels }}
+          cache-from: type=gha
+          cache-to: type=gha,mode=max
+          sbom: true
+          provenance: mode=max
+
+      - name: Scan image for vulnerabilities
+        if: github.event_name != 'pull_request'
+        uses: aquasecurity/trivy-action@915b19bbe73b92a6cf82a1bc12b087c9a19a5fe2 # v0.28.0
+        with:
+          image-ref: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }}
+          format: 'sarif'
+          output: 'trivy-results.sarif'
+          severity: 'CRITICAL,HIGH'
+

overseerr_mcp-1.0.1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,63 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*.*.*"
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: release
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: Verify tag matches pyproject.toml version
+        run: |
+          PKG_VERSION=$(grep -m1 '^version' pyproject.toml | sed 's/.*"\(.*\)".*/\1/')
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "Version mismatch: pyproject.toml=$PKG_VERSION tag=$TAG_VERSION"
+            exit 1
+          fi
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          attestations: true
+
+      - name: Create GitHub Release
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" \
+            --title "Release $GITHUB_REF_NAME" \
+            --generate-notes \
+            dist/*
+
+      - name: Install mcp-publisher
+        run: |
+          curl -fsSL "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
+
+      - name: Set version in server.json
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          jq --arg v "$VERSION" '
+            .version = $v |
+            .packages = [.packages[] | if .registryType == "pypi" then .version = $v else . end]
+          ' server.json > server.tmp && mv server.tmp server.json
+
+      - name: Authenticate to MCP Registry
+        run: ./mcp-publisher login dns --domain tootie.tv --private-key ${{ secrets.MCP_PRIVATE_KEY }}
+
+      - name: Publish to MCP Registry
+        run: ./mcp-publisher publish

overseerr_mcp-1.0.1/.gitignore

@@ -0,0 +1,86 @@
+# ── Secrets ──────────────────────────────────────────────────────────────────
+.env
+.env.*
+!.env.example
+
+# ── Runtime artifacts ────────────────────────────────────────────────────────
+logs/
+backups/
+*.log
+*.pid
+*.bak
+*.bak-*
+
+# ── Claude Code / AI tooling ────────────────────────────────────────────────
+.claude/settings.local.json
+.claude/worktrees/
+.omc/
+.lavra/
+.beads/
+.dolt/
+*.db
+*.db-shm
+*.db-wal
+.beads-credential-key
+.serena/
+.worktrees/
+.full-review/
+.full-review-archive-*
+.bivvy
+
+# ── IDE / editor ─────────────────────────────────────────────────────────────
+.vscode/
+.cursor/
+.windsurf/
+.1code/
+.idea/
+.zed/
+*.iml
+*.swp
+*.swo
+*~
+.emdash.json
+
+# ── OS generated ─────────────────────────────────────────────────────────────
+.DS_Store
+Thumbs.db
+
+# ── Caches (ALL tool caches go here) ─────────────────────────────────────────
+.cache/
+
+# ── Documentation artifacts (session/plan docs, not reference) ───────────────
+.docs/
+docs/plans/
+docs/sessions/
+docs/reports/
+docs/research/
+docs/superpowers/
+specs/
+
+# ── Python ───────────────────────────────────────────────────────────────────
+.venv/
+__pycache__/
+*.py[oc]
+*.egg-info/
+*.egg
+build/
+dist/
+sdist/
+wheels/
+pip-wheel-metadata/
+*.whl
+.hypothesis/
+.pytest_cache/
+.ruff_cache/
+.ty_cache/
+.mypy_cache/
+.pytype/
+.pyre/
+.pyright/
+htmlcov/
+.coverage
+.coverage.*
+coverage.xml
+.tox/
+.nox/
+pip-log.txt

overseerr_mcp-1.0.1/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "overseerr-mcp": {
+      "type": "http",
+      "url": "${OVERSEERR_MCP_URL}"
+    }
+  }
+}

overseerr_mcp-1.0.1/.pre-commit-config.yaml

@@ -0,0 +1,23 @@
+repos:
+  - repo: local
+    hooks:
+      - id: skills-validate
+        name: Validate skills
+        entry: just validate-skills
+        language: system
+        pass_filenames: false
+      - id: docker-security
+        name: Docker security check
+        entry: bash scripts/check-docker-security.sh
+        language: system
+        pass_filenames: false
+      - id: no-baked-env
+        name: No baked env vars
+        entry: bash scripts/check-no-baked-env.sh
+        language: system
+        pass_filenames: false
+      - id: ensure-ignore-files
+        name: Ensure ignore files
+        entry: bash scripts/ensure-ignore-files.sh --check
+        language: system
+        pass_filenames: false

overseerr_mcp-1.0.1/AGENTS.md

@@ -0,0 +1 @@
+CLAUDE.md

overseerr_mcp-1.0.1/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [1.0.1] - 2026-04-03
+
+### Fixed
+- **OAuth discovery 401 cascade**: BearerAuthMiddleware was blocking GET /.well-known/oauth-protected-resource, causing MCP clients to surface generic "unknown error". Added WellKnownMiddleware (RFC 9728) to return resource metadata.
+
+### Added
+- **docs/AUTHENTICATION.md**: New setup guide covering token generation and client config.
+- **README Authentication section**: Added quick-start examples and link to full guide.
+
+
+
+### Added
+- FastMCP server with `overseerr` and `overseerr_help` tools
+- Planned: BearerAuthMiddleware with startup token validation (not yet implemented in this release)
+- Dual transport (http/stdio via OVERSEERR_MCP_TRANSPORT)
+- Pagination for all list actions
+- Destructive ops confirmation gate

overseerr_mcp-1.0.1/CLAUDE.md

@@ -0,0 +1,41 @@
+# overseerr-mcp
+
+MCP server for Overseerr media request management.
+
+## Development
+
+- Language: Python (FastMCP + uv)
+- Port: 9151 (OVERSEERR_MCP_PORT)
+- Auth: Bearer token (OVERSEERR_MCP_TOKEN) + Overseerr API key (OVERSEERR_API_KEY)
+
+## Commands
+
+```bash
+just dev       # run locally
+just test      # run tests
+just lint      # ruff check
+just build     # docker build
+```
+
+
+## Version Bumping
+
+**Every feature branch push MUST bump the version in ALL version-bearing files.**
+
+Bump type is determined by the commit message prefix:
+- `feat!:` or `BREAKING CHANGE` → **major** (X+1.0.0)
+- `feat` or `feat(...)` → **minor** (X.Y+1.0)
+- Everything else (`fix`, `chore`, `refactor`, `test`, `docs`, etc.) → **patch** (X.Y.Z+1)
+
+**Files to update (if they exist in this repo):**
+- `Cargo.toml` — `version = "X.Y.Z"` in `[package]`
+- `package.json` — `"version": "X.Y.Z"`
+- `pyproject.toml` — `version = "X.Y.Z"` in `[project]`
+- `.claude-plugin/plugin.json` — `"version": "X.Y.Z"`
+- `.codex-plugin/plugin.json` — `"version": "X.Y.Z"`
+- `gemini-extension.json` — `"version": "X.Y.Z"`
+- `README.md` — version badge or header
+- `CHANGELOG.md` — new entry under the bumped version
+
+All files MUST have the same version. Never bump only one file.
+CHANGELOG.md must have an entry for every version bump.

overseerr_mcp-1.0.1/Dockerfile

@@ -0,0 +1,56 @@
+# syntax=docker/dockerfile:1
+
+# ── builder ──────────────────────────────────────────────────────────────────
+FROM python:3.11-slim AS builder
+
+COPY --from=ghcr.io/astral-sh/uv:0.10.10 /uv /uvx /bin/
+
+WORKDIR /app
+
+# Install dependencies first (layer cache)
+COPY pyproject.toml uv.lock* ./
+RUN touch README.md
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev --no-install-project
+
+# Copy source and install project
+COPY overseerr_mcp/ ./overseerr_mcp/
+RUN --mount=type=cache,target=/root/.cache/uv \
+    uv sync --frozen --no-dev
+
+# ── runtime ──────────────────────────────────────────────────────────────────
+FROM python:3.11-slim AS runtime
+
+RUN groupadd --gid 1000 mcpuser && \
+    useradd --uid 1000 --gid mcpuser --shell /bin/bash --create-home mcpuser && \
+    apt-get update && apt-get install -y --no-install-recommends wget && \
+    rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy the built venv and source from builder
+COPY --from=builder /app/.venv /app/.venv
+COPY --from=builder /app/overseerr_mcp /app/overseerr_mcp
+COPY --from=builder /app/pyproject.toml /app/pyproject.toml
+
+# Copy entrypoint
+COPY entrypoint.sh ./
+RUN chmod +x entrypoint.sh && \
+    mkdir -p /app/logs && \
+    chown -R mcpuser:mcpuser /app
+
+USER mcpuser
+
+EXPOSE 9151
+
+ENV PATH="/app/.venv/bin:$PATH" \
+    PYTHONUNBUFFERED=1 \
+    PYTHONDONTWRITEBYTECODE=1 \
+    OVERSEERR_MCP_HOST=0.0.0.0 \
+    OVERSEERR_MCP_PORT=9151 \
+    OVERSEERR_MCP_TRANSPORT=http
+
+HEALTHCHECK --interval=30s --timeout=10s --start-period=30s --retries=3 \
+    CMD wget -qO- http://localhost:9151/health || exit 1
+
+CMD ["./entrypoint.sh"]

overseerr_mcp-1.0.1/GEMINI.md

@@ -0,0 +1 @@
+CLAUDE.md