simkl-mcp

MCP server for Simkl — track movies, TV shows, and anime with autogenerated tools (Cloudflare Workers + Bun).

Setup

• Create a Simkl OAuth app and grab SIMKL_CLIENT_ID and SIMKL_CLIENT_SECRET (redirect URI must match .../oauth/callback).

• Add a .dev.vars (or Wrangler secrets) with:

  SIMKL_CLIENT_ID=your_client_id
  SIMKL_CLIENT_SECRET=your_client_secret
  OAUTH_REDIRECT_URI=http://localhost:8787/oauth/callback

• Install deps: bun install

Related MCP server: Trakt MCP Server

Local (SSE)

Run the worker with Wrangler and point your MCP client at the SSE endpoint.

bun run dev

Add to claude_desktop_config.json (or equivalent):

{
  "mcpServers": {
    "simkl": {
      "transport": "sse",
      "url": "http://localhost:8787/sse"
    }
  }
}

On first connect, you’ll be redirected to Simkl to approve access, then dropped back to /oauth/callback.

Deploy (Cloudflare Workers)

wrangler secret put SIMKL_CLIENT_ID
wrangler secret put SIMKL_CLIENT_SECRET
wrangler secret put OAUTH_REDIRECT_URI # e.g., https://your-worker.workers.dev/oauth/callback
bun run deploy            # staging
bun run deploy:production # optional

Use https://your-worker.workers.dev/sse for remote SSE connections (Claude: Settings → Connectors → Add Server).

Tools

• Search: simkl_search, simkl_search_id

• Scrobble: simkl_scrobble_start, simkl_scrobble_pause, simkl_scrobble_stop

• Sync/Tracking: simkl_sync_add_to_list, simkl_sync_history, simkl_sync_history_remove, simkl_sync_ratings, simkl_sync_ratings_remove

• Discovery: trending/best/details/episodes/genres for tv, movies, anime (13 tools)

• User: simkl_users_stats, plus custom simkl_my_stats

• Resources: watchlist/{type}/{status}, trending/{type}/{interval}

Authentication

• Public requests add client_id as a query param; authenticated calls use Authorization: Bearer <token>.

• The Worker handles OAuth: /auth/simkl redirects to Simkl, /oauth/callback exchanges the code and issues MCP credentials.

• Tokens are long-lived; for local dev, secrets live in .dev.vars, for production use Wrangler secrets and KV (OAUTH_KV) for state.

Development

# regenerate tools from the OpenAPI spec
bun run codegen

# typecheck
bun run typecheck

# health check
curl http://localhost:8787/health

License

MIT