Allegro Open

CI License: MIT Python 3.10+ mypy: strict

A Python MCP server for the Allegro REST API, backed by a separable allegro_client SDK under the hood.

src/
├── allegro_client/    # MCP-agnostic — extractable as its own PyPI package
└── allegro_mcp/       # FastMCP wrapper exposing 268 tools

Highlights

• 268 MCP tools spanning all ~30 Allegro resource groups (offers, orders, shipments, messaging, billing, returns, disputes, payments, promotions, fulfillment, …).
• Four OAuth flows: Device Code (recommended for MCP), Authorization Code with PKCE, Client Credentials, and pre-shared refresh token.
• Persistent token store at ~/.allegro-mcp/tokens.json (mode 0600, atomic writes, refresh-token rotation handled automatically).
• Sandbox + production environments with a single env-var flip.
• Write gate — high-blast-radius mutating tools refuse to fire unless ALLEGRO_ENABLE_WRITES=true. Default is read-mostly safe.
• Generated Pydantic models codegen'd from Allegro's official OpenAPI 3.0 spec via datamodel-code-generator.
• Production-grade tooling: mypy --strict, ruff, pre-commit hooks, multi-stage Docker build, GitHub Actions CI on Python 3.10/3.11/3.12.
• 250+ unit tests, including a layer-enforcement test that protects the future package-extraction boundary.
• MIT-licensed, not affiliated with Grupa Allegro. Third-party runtime-dependency licenses are inventoried in THIRD_PARTY_NOTICES.md.

Quickstart

The fastest path is uvx — no clone, no virtualenv, no install:

ALLEGRO_CLIENT_ID=your-client-id \
ALLEGRO_CLIENT_SECRET=your-client-secret \
ALLEGRO_AUTH_FLOW=device \
uvx --from git+https://github.com/piotrlinski/allegro-open-mcp-server allegro-mcp

uvx resolves the package, installs it into an ephemeral venv, and runs the allegro-mcp console script. The first run with ALLEGRO_AUTH_FLOW=device prints a verification URL + user code to stderr; approve in your browser and the refresh token persists at ~/.allegro-mcp/tokens.json for next time.

To pin a version (or test a branch / PR), append @<rev>:

uvx --from git+https://github.com/piotrlinski/[email protected] allegro-mcp

CLI flags work the same as env vars — handy when wiring an MCP client:

uvx --from git+https://github.com/piotrlinski/allegro-open-mcp-server allegro-mcp \
    --client-id  your-client-id \
    --client-secret  your-client-secret \
    --auth-flow  device \
    --environment  sandbox

If you'd rather work from a clone:

git clone https://github.com/piotrlinski/allegro-open-mcp-server
cd allegro-open-mcp-server

uv sync --extra dev
cp .env.example .env             # fill in ALLEGRO_CLIENT_ID, ALLEGRO_CLIENT_SECRET, ALLEGRO_AUTH_FLOW
uv run allegro-mcp               # speaks MCP over stdio

Full walkthrough → docs/tutorials/quickstart.md.

Authentication

Flow	When to use
device (recommended)	Headless MCP server; first run prints URL+code to stderr
authcode	Operator on the same host; spawns localhost callback listener
client_credentials	App-only access to public resources only
refresh_token	Pre-shared refresh token, no interactive auth

Pick one with docs/how-to/oauth-flows.md.

MCP client setup

• Claude Desktop — docs/how-to/with-claude-desktop.md
• Claude Code — docs/how-to/with-claude-code.md
• MCP Inspector — make inspector

Development

make sync                  # install dev dependencies
make test                  # run pytest (250+ tests)
make lint                  # ruff + mypy --strict
make format                # apply ruff formatting + auto-fixes
make gen-models            # regenerate Pydantic models from the OpenAPI spec
make gen-tools             # regenerate MCP tool modules from the spec
make check-models-freshness   # warn if upstream spec moved
make build                 # build the Docker image
make run                   # run the server in Docker (stdio)
make inspector             # run MCP Inspector against the Docker image
make docs-serve            # live-reload docs at http://127.0.0.1:8000

Architecture

Two packages, one wheel today, two future PyPI distributions:

allegro_client.config → allegro_client.errors → allegro_client.auth →
  allegro_client.http → allegro_client.models           # MCP-agnostic SDK

allegro_mcp.config → allegro_mcp.errors → allegro_mcp.logging →
  allegro_mcp.tools → allegro_mcp.server                # FastMCP wrapper

The boundary is enforced by tests/unit/test_architecture.py — CI fails if allegro_client ever imports fastmcp, mcp, or allegro_mcp.*.

Read more: docs/explanation/architecture.md

Contributing

PRs welcome. See CONTRIBUTING.md.

Security

Found a vulnerability? Please follow SECURITY.md.

License

MIT — community project; not affiliated with Grupa Allegro.