pinkbee-mcp

Unofficial community integration; not affiliated with or supported by Pinkbee.

Proof of concept.

A read-only MCP server for Pinkbee (*.mijnpinkbee.nl), an online platform for planning shifts and managing volunteers.

It lets an AI assistant answer questions about a roster — which shifts still need people, who is scheduled, who is in which group — and nothing more: it cannot book, cancel or change anything.

Run it

1. Get the docker compose file

curl -fsSLO https://raw.githubusercontent.com/withoutanickname/pinkbee-mcp/main/docker-compose.yml

2. Deploy docker compose

docker compose up -d

That is all. It pulls withoutanickname/pinkbee-mcp and starts on built-in sample data, so there is nothing to configure and no risk to anyone's real roster. The MCP endpoint is then on http://<server-lan-ip>:8087/mcp (and on http://127.0.0.1:8087/mcp from the server itself).

Without compose:

docker run -d --name pinkbee-mcp -p 8087:8080 withoutanickname/pinkbee-mcp

To build from this checkout instead, uncomment build: . in docker-compose.yml and run docker compose up -d --build.

Point your MCP client at that URL, or try it from the terminal:

curl -s -X POST http://127.0.0.1:8087/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"pinkbee_check_connection","arguments":{}}}' | sed -n 's/^data: //p' | jq -r '.result.content[0].text'

Related MCP server: Slack MCP Server

Available calls

Group and shift names are chosen by each Pinkbee administrator, so nothing here assumes any particular naming: pinkbee_list_groups_and_shifts returns the whole list and the assistant matches the names itself.

All calls are enabled by default. Disable one or more by putting their full names in the comma-separated blacklist:

PINKBEE_DISABLED_CALLS=pinkbee_list_group_emails,pinkbee_list_registrations

Disabled calls are removed from discovery as well as invocation. An unknown name is treated as a configuration error instead of being silently ignored.

Connect it to a real Pinkbee

cp .env.example .env

Set these four, then docker compose up -d:

PINKBEE_DATA_SOURCE=live
PINKBEE_BASE_URL=https://your-organisation.mijnpinkbee.nl
PINKBEE_LOGIN=
PINKBEE_PASSWORD=

Use an account that only needs to read the roster. Compose reads these values from .env; every supported variable and default is visible under environment in docker-compose.yml.

Network access

The Compose service listens on all host interfaces so another service on the LAN can connect without extra configuration. By default, every sender that can reach port 8087 is allowed. A bearer token is recommended even on a trusted LAN.

When upgrading from an older release that published only on 127.0.0.1, note that this default deliberately adds LAN access. Set a token and/or sender allowlist before upgrading a live deployment if the LAN is not fully trusted.

To restrict access, set exact sender IPs or DNS names:

PINKBEE_ALLOWED_SENDERS=192.168.1.42,agent.domain.example.com

This allowlist checks the IP of the client or service making the MCP request. It does not list the current machine's/server's own IP. DNS names are resolved to sender IPs once when the MCP starts. Behind a reverse proxy, the sender seen by the MCP is normally the proxy; see docs/deploying.md.

Browser requests carrying an Origin header are rejected to prevent a web page from driving the LAN service through DNS rebinding. Normal MCP clients do not send it.

Safety

• Read-only. Every request to Pinkbee is a GET. The only POST in the whole codebase is the login itself.

• Mock data by default. Reaching a live instance needs a deliberate PINKBEE_DATA_SOURCE=live and credentials, or the server refuses to start.

• Personal data is off by default. The two tools that return names or email addresses refuse until you set PINKBEE_ALLOW_PERSONAL_DATA=true.

• A filter can never widen by accident. An id that does not exist is an error, an unknown argument name is refused, and asking for every shift takes an explicit all_shifts=true. Date ranges and id lists are capped.

• Credentials only over HTTPS. A plain http:// Pinkbee URL is refused, since logging in sends the password.

• Simple network policy. LAN access is on by default. Use PINKBEE_ALLOWED_SENDERS for sender-IP filtering and PINKBEE_MCP_TOKEN for a shared bearer token. There is no TLS inside the container, so use a trusted LAN or put a TLS reverse proxy in front.

• One exception, on purpose: PINKBEE_LOG_LEVEL=DEBUG also turns on the libraries' debug output, which prints whole response bodies — so personal data does appear in debug logs. Use it while troubleshooting, not in normal running. See docs/deploying.md.

Documentation

Licence

MIT.