bizidashboard-mcp

MCP server exposing BiziDashboard's historical and analytical data for the Zaragoza Bizi bike-share system as tools for LLM clients.

Unlike the official GBFS feed (which only exposes the current state of the system), BiziDashboard stores and analyzes history: rankings, occupancy patterns, mobility signals, alert history, and a station rebalancing diagnostic report. This server makes that analytical layer easy to query from Claude Desktop or any other MCP client.

Installation

Published on npm — no cloning or compiling required. Add it to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "bizidashboard": {
      "command": "npx",
      "args": ["-y", "bizidashboard-mcp"]
    }
  }
}

From source

git clone https://github.com/gcaguilar/bizidashboard-mcp.git
cd bizidashboard-mcp
npm install
npm run build

Then point your MCP client at the built entrypoint:

{
  "mcpServers": {
    "bizidashboard": {
      "command": "node",
      "args": ["/absolute/path/to/bizidashboard-mcp/dist/index.js"]
    }
  }
}

Related MCP server: Spanish Public Data MCP

Configuration

BiziDashboard API (outbound)

HTTP Server & OAuth (inbound, remote clients only)

The HTTP server requires OAuth-based authentication via Auth0. Before running it, you must:

1. Create an Auth0 API for the MCP resource, with exact identifier https://mcp.datosbizi.com/mcp, RS256, and scopes read:dashboard and read:exports. Enable Dynamic Client Registration and Resource Parameter Compatibility Profile in the tenant. Claude and ChatGPT then register their own public clients; users do not receive an OAuth secret.

2. In Applications → APIs → the MCP API, select Add Application to create its Custom API Client. Grant that client user-delegated access to https://api.datosbizi.com and enable On-Behalf-Of Token Exchange. It is not the ordinary Machine-to-Machine application. Keep its client secret only in the MCP deployment.

3. Configure these environment variables:

Do not set AUTH0_AUDIENCES, AUTH0_ACCESS_TOKEN_ALLOWED_CLIENT_IDS, AUTH0_CLIENT_IDS, or OAUTH_PROXY_ORIGIN on this public DCR deployment. BASE_URL is required in production and must be the HTTPS MCP URL. Set BIZI_ALLOWED_API_HOSTS to an explicit comma-separated allowlist (normally datosbizi.com) so authenticated tokens are never forwarded to an unintended origin.

For local authenticated use, enable Device Authorization for a local DatosBizi Auth0 client and run bizidashboard-mcp-login with AUTH0_DOMAIN, AUTH0_CLIENT_ID and AUTH0_AUDIENCE. It stores tokens in ~/.config/bizidashboard-mcp/tokens.json; the stdio server refreshes them when a refresh token is available. Set BIZI_TOKEN_FILE to override that path.

Stdio Server (Claude Desktop, no auth needed)

All BIZI_* variables above are optional; if omitted, they default to the public BiziDashboard. The stdio server (bizidashboard-mcp) needs no authentication.

Tools

Every tool remains visible to every authenticated remote user. Every tool returns the API's JSON response as-is (or CSV text when format: "csv" is requested); nothing is summarized or transformed. An elevated request without read:exports returns an actionable authorization error telling the user to reconnect with that scope. Other upstream errors (bad params, rate limits) retain their original status and message.

Remote connector (Claude / ChatGPT)

npx bizidashboard-mcp (stdio) only works for local clients like Claude Desktop. To use this data from claude.ai remote connectors or ChatGPT, run the HTTP server instead and expose it publicly over HTTPS. It exposes the same nine tools through one standard MCP endpoint:

Every route except /healthz requires an OAuth bearer token (Authorization Code flow with Auth0), obtained after registering as described above. The remote server validates issuer, MCP audience, signature, expiry, azp (when configured), and read:dashboard. It then performs an Auth0 On-Behalf-Of exchange, so BiziDashboard receives a token for https://api.datosbizi.com, preserving the signed-in user and their scopes without accepting an MCP token at the downstream API.

Run it on your own server

With Docker (image published to GHCR on every push to main/tag by .github/workflows/docker-publish.yml):

docker run -d \
  --name bizidashboard-mcp \
  -p 8787:8787 \
  -e AUTH0_DOMAIN=<your-auth0-domain> \
  -e MCP_AUTH0_AUDIENCE=https://mcp.yourdomain.com/mcp \
  -e API_AUTH0_AUDIENCE=https://api.datosbizi.com \
  -e MCP_AUTH0_CLIENT_ID=<obo-client-id> \
  -e MCP_AUTH0_CLIENT_SECRET=<obo-client-secret> \
  -e BASE_URL=https://mcp.yourdomain.com \
  ghcr.io/gcaguilar/bizidashboard-mcp:latest

From source:

npm install
npm run build
AUTH0_DOMAIN=<your-auth0-domain> \
MCP_AUTH0_AUDIENCE=https://mcp.yourdomain.com/mcp \
API_AUTH0_AUDIENCE=https://api.datosbizi.com \
MCP_AUTH0_CLIENT_ID=<obo-client-id> \
MCP_AUTH0_CLIENT_SECRET=<obo-client-secret> \
  npm run start:http

Either way, put it behind a reverse proxy (Caddy, nginx, Traefik, …) on your VPS to terminate TLS on a real domain — https://mcp.yourdomain.com — since neither client below will call a plain-HTTP or self-signed endpoint.

Register it

• Claude (claude.ai → Settings → Connectors → Add custom connector): URL https://mcp.yourdomain.com/mcp. Authentication is OAuth 2.0 Authorization Code; Claude will discover the flow automatically via /.well-known/oauth-protected-resource.

• ChatGPT MCP / GPT builder: use the MCP URL and let the client complete OAuth through Dynamic Client Registration. Do not embed the OBO client secret in ChatGPT or in a public page.

OpenAI plugin submission

The MCP-only plugin package is in plugins/bizidashboard-mcp. It includes the directory metadata and starter prompts for ChatGPT/Codex. Submission copy and review cases are in docs/openai-plugin-submission.md. The public submission still needs a verified OpenAI publisher identity, legal URLs, regional availability, and OAuth reviewer credentials.

Development

npm run build       # compile TypeScript to dist/ (both the stdio and HTTP entrypoints)
npm run typecheck   # type-check without emitting
npm test            # build, then run integration tests against the live public API
  npm run start:http  # run the HTTP MCP server locally (needs the Auth0 MCP/OBO variables above)

To build the Docker image locally: docker build -t bizidashboard-mcp .

The existing tool smoke tests hit https://datosbizi.com for real. Focused authorization tests use no live credentials and verify that remote HTTP requests never send BIZI_PUBLIC_API_KEY.