Fake Pennylane MCP Server

An open-source fake server that emulates the Pennylane MCP experience for local development, automated tests, demos, and CI pipelines — without requiring a real Pennylane account or real accounting data.

Status: working early implementation. The repository now includes a runnable Streamable HTTP MCP server, deterministic fixtures, scenario packs, static bearer auth, and a fake OAuth flow for callback/integration testing.

Why this project exists

Pennylane MCP is useful, but it is hard to validate an integration when you do not have:

• a real Pennylane account,
• a portfolio of test companies and customers,
• deterministic accounting fixtures,
• a safe environment for demos and CI.

This project solves that gap by providing a predictable, developer-friendly test double for a Pennylane-like MCP server.

Current capabilities

The current implementation provides:

• a Streamable HTTP MCP server,
• deterministic fixture loading from JSON,
• scenario-pack selection,
• optional static bearer token authentication,
• a fake OAuth authorization-code flow for end-to-end callback testing,
• automated local tests for runtime, scenarios, and auth.

Exposed tools

• get_context
• get_company
• list_companies
• list_customers
• get_customer
• list_customer_invoices

Quickstart

Requirements

• Python 3.11+
• uv

Install dependencies

cd /home/leyriel/dev/fake-pennylane-mcp-server
uv sync

Run the server

Default fixture dataset, no auth:

uv run python -m fake_pennylane_mcp_server --host 127.0.0.1 --port 8000

With a scenario pack:

uv run python -m fake_pennylane_mcp_server \
  --host 127.0.0.1 \
  --port 8000 \
  --scenario unpaid_invoice

With static bearer auth:

uv run python -m fake_pennylane_mcp_server \
  --host 127.0.0.1 \
  --port 8000 \
  --auth-mode static_bearer \
  --bearer-token test-secret-token

With fake OAuth flow:

uv run python -m fake_pennylane_mcp_server \
  --host 127.0.0.1 \
  --port 8000 \
  --auth-mode fake_oauth

Run with Docker Compose

Build and start the default server:

docker compose up --build

Run detached:

docker compose up --build -d

Stop it:

docker compose down

If port 8000 is already used on your machine, override the published host port:

PUBLISHED_PORT=8080 docker compose up --build -d

Use a scenario pack:

SCENARIO_NAME=unpaid_invoice docker compose up --build

Use static bearer auth:

AUTH_MODE=static_bearer BEARER_TOKEN=test-secret-token docker compose up --build

Use fake OAuth mode:

AUTH_MODE=fake_oauth docker compose up --build

By default Compose exposes the server on http://127.0.0.1:${PUBLISHED_PORT:-8000}/mcp and mounts ./fixtures read-only into the container.

Scenario packs

The default fixture file currently exposes these scenario packs:

• default
• customer_found
• customer_not_found
• unpaid_invoice
• multi_company

Each scenario narrows the deterministic dataset to a stable business situation.

Authentication modes

none

Default mode. No Authorization header is required.

static_bearer

Requires a bearer token on MCP HTTP requests.

Example header:

Authorization: Bearer ***

fake_oauth

Exposes a minimal fake OAuth authorization server alongside the MCP resource server.

Included endpoints:

• /.well-known/oauth-authorization-server
• /.well-known/oauth-protected-resource/mcp
• /authorize
• /token

Current fake client contract:

• client_id: fake-public-client
• token endpoint auth method: none
• redirect URIs:
  • http://127.0.0.1:9999/callback
  • http://localhost:9999/callback
• scope: mcp:access

This flow is meant for local integration tests and fake callback simulations — not as a production OAuth server.

Compatibility and status tracking

See:

• docs/compatibility-matrix.md
• docs/README.md

Example clients

See:

• examples/basic_client.py
• examples/bearer_client.py
• examples/README.md

Running tests

uv run pytest -q

Development workflow

Typical local loop:

1. update fixtures / scenarios / auth behavior,
2. run uv run pytest -q,
3. run one of the example clients against a local server,
4. commit the change.

Project structure

.
├── docs/
├── examples/
├── fixtures/
├── src/
├── tests/
├── CONTRIBUTING.md
├── Dockerfile
├── docker-compose.yml
├── LICENSE
├── README.md
└── pyproject.toml

Roadmap

Bootstrap

• [x] Create Plane project
• [x] Create public GitHub repository
• [x] Publish initial detailed README
• [x] Prepare repo structure for implementation handoff

Implementation milestones

• [x] Implement fake Streamable HTTP MCP runtime
• [x] Add deterministic fixture loading
• [x] Add fake customer / invoice queries
• [x] Add scenario packs
• [x] Add auth modes for integration testing
• [x] Add runnable example clients
• [x] Add fake OAuth flow for end-to-end callback testing
• [x] Publish a compatibility matrix
• [x] Add Docker and Docker Compose local runtime

Next useful milestones

• [ ] add GitHub Actions CI once a token with workflow scope is available
• [ ] enrich compatibility with more Pennylane-like tools
• [ ] add more domain fixture packs
• [ ] add standalone OAuth example client
• [ ] document additional integration recipes

Open-source direction

The intent is for this project to be genuinely useful to a broader audience, not just a one-off internal spike.

That means we optimize for:

• clarity of documentation,
• ease of local setup,
• stable deterministic fixtures,
• transparent scope,
• simple contribution paths.

Project origin

This repository was spun out from work around a MissionGuard integration effort, where a Pennylane MCP replacement strategy needed a realistic test environment without depending on a real Pennylane tenant.

License

MIT.

Disclaimer

This project is not affiliated with or endorsed by Pennylane. It is an independent open-source testing utility intended to emulate part of a Pennylane-like MCP integration surface for development and testing purposes only.