BetaSeries MCP Server

An open-source Model Context Protocol server for the BetaSeries API — TV show and movie tracking, planning, ratings, social features, and more. Self-hostable via Docker, or run locally over stdio with any MCP client.

Features

• 186 BetaSeries operations, grouped into 23 tools (one per API resource category) so an LLM client doesn't choke on tool count — every real endpoint the API exposes is reachable, with none of the noise of one-tool-per-endpoint.

• Generated straight from BetaSeries' own OpenAPI spec (scripts/generate-tools.ts), so keeping up with API changes is a re-vendor + npm run codegen, not hand-editing 190 parameter lists.

• Both stdio (local MCP clients) and Streamable HTTP (Docker / remote) transports from the same server.

• Auth is a one-time npm run auth (OAuth2 device-code flow) — the running server never exposes a "log in" tool to the LLM.

Tool categories

Each tool takes operation (an enum of that category's operation IDs) and params (a string key/value map for that operation) — the full parameter reference for every operation is in the tool's own MCP description, generated from the spec.

Related MCP server: Trakt MCP Server

⚠️ A note on openapi.json

BetaSeries' published spec (https://developers.betaseries.com/openapi.json) contains 7 extra operations tagged "Model" — /discover, /resources, /resources/{id}, /query, /execute, /version, /setCredentials — worded like Model Context Protocol primitives ("Discover MCP server capabilities", "Execute an action through the MCP server", "Set API key... for LLM authentication"). They do not exist on the real API (api.betaseries.com returns a plain Page not found. for all of them, unlike real endpoints), and there's no BetaSeries announcement of an official MCP server. They look like either leftover boilerplate from a spec-generation tool, or bait aimed at AI agents auto-generating MCP servers from this exact file. Either way, this project strips them — see spec/PROVENANCE.md for the full writeup. If BetaSeries ships a real MCP server later, treat this project as a candidate for archival in favor of theirs.

Setup

1. Get a BetaSeries API key

Register an application at BetaSeries to get an API key (and secret, needed for step 3) — see developers.betaseries.com.

2. Install

git clone https://github.com/framinosona/betaseries-mcp.git
cd betaseries-mcp
npm install
cp .env.example .env
# edit .env: set BETASERIES_API_KEY (and BETASERIES_API_SECRET for the next step)

3. Authenticate (one-time)

npm run auth

This runs BetaSeries' OAuth2 device-code flow: it prints a code and a URL, you approve it in your browser, and the resulting access token is saved into .env automatically as BETASERIES_ACCESS_TOKEN.

4. Run

Locally over stdio (default):

npm run build
npm start

Or for development, without a build step:

npm run dev

5. Point an MCP client at it

For Claude Code / Claude Desktop, add to your MCP config:

{
  "mcpServers": {
    "betaseries": {
      "command": "node",
      "args": ["/path/to/betaseries-mcp/dist/index.js"],
      "env": {
        "BETASERIES_API_KEY": "...",
        "BETASERIES_ACCESS_TOKEN": "..."
      }
    }
  }
}

Self-hosting with Docker

cp .env.example .env   # fill in your key/token as above
docker compose up -d

This runs the server in Streamable HTTP mode on http://localhost:3000/mcp (/health for a liveness check). Point any MCP client that supports Streamable HTTP at that URL. To run npm run auth against the containerized build instead of locally, use docker compose run --rm betaseries-mcp npm run auth.

Environment variables

Development

npm run codegen    # spec/betaseries-openapi.json -> src/generated/operations.ts
npm run typecheck
npm test

To pick up a BetaSeries API change: re-fetch https://developers.betaseries.com/openapi.json, strip any "Model"-tagged operations (see spec/PROVENANCE.md), overwrite spec/betaseries-openapi.json, then npm run codegen.

License

MIT — see LICENSE.md.