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

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