Projonatics MCP Server

Exposes the Projonatics API to Claude Code (or any MCP client) as tools: read clients, projects, tasks, milestones, payment milestones, financial summaries, dashboard and alerts, and — unless registered read-only — create and update them too.

It talks to a running Projonatics backend over HTTPS using a personal API token, so it sees and can change exactly what that user can in the app (role-based scoping applies), and every change is recorded in the audit log under that user.

1. Get an API token

In the app: open your profile menu (top right) → Claude Code (MCP) → Generate token. The key is shown once.

Or mint one on the server:

# production (docker)
docker compose -f docker-compose.prod.yml exec backend python manage.py drf_create_token you@company.com

# local
cd backend && python manage.py drf_create_token you@company.com

GET /api/me/api-token/ reports whether a token exists; DELETE revokes it; POST again rotates it.

2. Register with Claude Code

Published on PyPI as projonatics-mcp; uvx installs it on first run:

claude mcp add -s user projonatics \
  -e PROJONATICS_URL=https://<your-domain> \
  -e PROJONATICS_TOKEN=<token> \
  -- uvx projonatics-mcp

From a local clone (development): -- uv run --directory /absolute/path/to/projonatics/mcp projonatics-mcp. To pick up a newer release: uv cache clean projonatics-mcp and restart Claude Code.

Check with claude mcp get projonatics. Re-run claude mcp remove projonatics -s user then add to change the URL or token.

Read-only mode

Add PROJONATICS_READ_ONLY=1 to register only the read tools (Claude cannot create, edit or delete anything):

claude mcp add -s user projonatics \
  -e PROJONATICS_URL=https://<your-domain> \
  -e PROJONATICS_TOKEN=<token> \
  -e PROJONATICS_READ_ONLY=1 \
  -- uvx projonatics-mcp

This is a client-side switch: it decides which tools the server offers, not what the token can do. Accepted values: 1, true, yes, on.

Tools

Read tools

Write tools

Not registered when PROJONATICS_READ_ONLY is set. Update tools change only the fields you pass; pass '' to clear a nullable field. Money is passed as decimal strings, dates as YYYY-MM-DD.

The token's role is enforced by the API: a viewer token gets 403 on every write, a user token can write tasks and milestones on its projects, admins can write everything. The error message says which role is needed. Every tool carries MCP annotations (readOnlyHint, destructiveHint), so clients such as Claude Code can ask for confirmation appropriately.

Development

cd mcp
uv sync
uv run pytest

Tests mock the HTTP transport; no backend needed.

Releasing

Bump version in pyproject.toml, commit, then tag and push:

git tag mcp-v0.2.0 && git push origin mcp-v0.2.0

.github/workflows/publish-mcp.yml runs the tests, builds, and publishes to PyPI via trusted publishing.