vikey-mcp-server

An MCP (Model Context Protocol) server that exposes the Vikey API to any MCP-compatible AI client (Cursor, Claude Desktop, etc.).

Tools

Requirements

• Python ≥ 3.10
• A valid Vikey API key

Installation

Via uvx (recommended – no install needed)

uvx vikey-mcp-server

Via pip

pip install vikey-mcp-server
vikey-mcp-server

Configuration

Set the VIKEY_API_KEY environment variable before starting the server:

export VIKEY_API_KEY=your_api_key_here

Cursor / Claude Desktop integration

Add the following block to your MCP client configuration file.

Cursor (~/.cursor/mcp.json or .cursor/mcp.json in the project):

{
  "mcpServers": {
    "vikey": {
      "command": "uvx",
      "args": ["vikey-mcp-server"],
      "env": {
        "VIKEY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "vikey": {
      "command": "uvx",
      "args": ["vikey-mcp-server"],
      "env": {
        "VIKEY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Tool reference

list_external_reservations

list_reservations

list_locals

get_reservation_detail

get_reservation_services

Development

# Clone and install
git clone https://github.com/tosettil/vikey-mcp-server.git
cd vikey-mcp-server
uv sync

# Run locally
VIKEY_API_KEY=your_key uv run vikey-mcp-server

Release workflow

Releases are automated via GitHub Actions. Use the Bump version workflow from the Actions tab to choose patch, minor, or major. The workflow will:

1. Bump the version in pyproject.toml
2. Create and push the corresponding vX.Y.Z tag
3. The tag push triggers the Publish workflow, which builds and pushes the package to PyPI

One-time setup

• PyPI Trusted Publisher: on pypi.org, configure a trusted publisher for this project pointing at tosettil-polimi/vikey-mcp-server, workflow publish.yml. No PYPI_API_TOKEN is required.
• RELEASE_PAT repository secret: create a fine-grained Personal Access Token with contents: write permission on this repo and add it as the RELEASE_PAT secret. This is required because pushes made with the default GITHUB_TOKEN do not trigger other workflows (GitHub's anti-loop protection), so without a PAT the tag pushed by bump-version.yml would never trigger publish.yml.

License

MIT