qgenda

QGenda Claude Code Plugin

A Claude Code plugin for querying the QGenda scheduling system. Covers 15 read-only API endpoints including schedules, staff, open shifts, time-off requests, rotations, audit logs, and more.

Install

1. Get your QGenda API credentials

Create ~/.qgenda.conf:

[qgenda]
company_key = YOUR-COMPANY-KEY
username = YOUR-API-USERNAME
password = YOUR-API-PASSWORD
api_url = https://api.qgenda.com/
api_version = v2

chmod 600 ~/.qgenda.conf

2. Install the plugin

claude plugin marketplace add lancereinsmith/claude-qgenda-plugin
claude plugin install qgenda@claude-qgenda-plugin

That's it. Restart Claude Code and you're ready to go.

Verify

claude plugin list    # should show qgenda
claude mcp list       # should show qgenda with 15 tools

Update

claude plugin marketplace update claude-qgenda-plugin
claude plugin update qgenda@claude-qgenda-plugin

Restart Claude Code after updating.

How to Use

Invoke the skill explicitly

Type /qgenda followed by your question:

/qgenda Who is working next Monday?
/qgenda Show me Dr. Smith's schedule for January
/qgenda What shifts need coverage this week?
/qgenda Who has requested time off in March?
/qgenda What rotation is Dr. Jones on?

Just ask naturally

The skill auto-invokes for scheduling questions:

"Who's on call this weekend?"
"What's my schedule next week?"
"Are there any open shifts I can pick up?"
"Who changed the Friday schedule?"

Supported queries

Category	What you can ask
Schedules	Who is working today? What's Dr. Smith's schedule next week?
Open shifts	What shifts need coverage? Are there any unfilled shifts this week?
Staff	List all staff members. Who has the "Neuro Lite" sub-specialty?
Staff detail	Show me everything about Dr. Jones (tags, skillset, profiles).
Requests	Who has requested time off next month? Any pending swap requests?
Rotations	What rotation is Dr. Smith on? Show rotations for Q1.
Audit log	Who changed the schedule for last Monday?
Tasks	What shift types exist? Show task details with profiles.
Facilities	List all facilities.
Time events	What time events are logged for today?
Daily cases	Show daily cases for this week.
Daily config	List daily configurations.
Rooms	What rooms are available?
Patient encounters	Show encounters for a given daily config and date.

Customizing the Skill

Add practice-specific context

After installing, you can customize the skill by editing SKILL.md in your plugin directory. For example:

## Practice Context

- Our company has 12 physicians
- Task "BR" means Breast Imaging, "CT1" means CT Reading Room 1
- Dr. Smith's last name in QGenda is "Smith-Jones"

Prevent auto-invocation

If you want the skill to only activate when you explicitly type /qgenda, add this to the SKILL.md frontmatter:

disable-model-invocation: true

Alternative credential methods

Instead of a config file, you can use environment variables:

export QGENDA_EMAIL=your-api-username
export QGENDA_PASSWORD=your-api-password
export QGENDA_COMPANY_KEY=your-company-key

For a config file at a non-standard location:

export QGENDA_CONF_FILE=/path/to/your/qgenda.conf

Alternative setup methods

Most users should use the plugin install above. These alternatives are for specific use cases.

Claude Code (MCP server only, no skill)

claude mcp add qgenda \
  -e QGENDA_CONF_FILE=~/.qgenda.conf \
  -- uv run --directory ~/Maker/claude-qgenda-plugin mcp run server.py:mcp

Claude Desktop

Claude Desktop does not support plugins. Add the MCP server manually to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "qgenda": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/claude-qgenda-plugin",
        "mcp", "run", "server.py:mcp"
      ],
      "env": {
        "QGENDA_CONF_FILE": "/path/to/.qgenda.conf"
      }
    }
  }
}

Then restart Claude Desktop.

Docker

docker compose up -d              # Starts on port 8000 (SSE transport)
MCP_PORT=9000 docker compose up -d  # Custom port

Credentials are mounted from ~/.qgenda.conf as a Docker secret.

Manual install to personal skills

just install       # copies to ~/.claude/skills/qgenda/
just uninstall     # removes it

As a tarball

For environments without GitHub access:

just package       # creates dist/qgenda-skill-X.Y.Z.tar.gz

Recipient installs with:

tar xzf qgenda-skill-<version>.tar.gz
cd qgenda-skill && ./install.sh

See INSTALL.md for full details on all setup methods.

Troubleshooting