# simkl-mcp

![AI Slop](https://img.shields.io/badge/vibe_coded-claude_sonnet_4.5-orange?style=flat&logo=claude&label=vibe%20coded)


[MCP](https://modelcontextprotocol.io/docs/getting-started/intro) server for [Simkl](https://simkl.com) — track movies, TV shows, and anime with autogenerated tools (Cloudflare Workers + Bun).

![img.png](docs/img.png)

## 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:
  ```bash
  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.
```bash
bun run dev
```
Add to `claude_desktop_config.json` (or equivalent):
```json
{
  "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)
```bash
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
```bash
# regenerate tools from the OpenAPI spec
bun run codegen

# typecheck
bun run typecheck

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

## License
MIT