Unanet MCP Server for Claude Desktop

Warning

Writing to timesheets is turned off by default. If you decide to change this, be very careful, and always keep a human in the loop. These tools can add, edit, delete, and submit real time entries on a live government-contract ERP. An AI assistant can misread a request or pick the wrong project, date, or hours. Before submitting any timesheet, review it yourself in Unanet and confirm every entry is correct. Submission is one-way and locks the timesheet. Never let an agent submit on your behalf without your own final check.

This fork lets Claude Desktop talk to Nava's Unanet GovCon instance through the Model Context Protocol (MCP). It has been substantially updated from the original API-key design to use Unanet Platform REST: username/password login, short-lived bearer tokens, and safe-by-default tool registration.

The happy path is macOS + Claude Desktop.

What works today

By default, the server exposes one safe read-only tool:

unanet_get_my_leave_balances — reads your Unanet leave balances with minimized output.

Example in Claude Desktop:

With explicit opt-in, the server can also expose additional Platform REST read tools:

unanet_get_projects
unanet_get_project_details
unanet_get_project_status
unanet_get_timesheets
unanet_get_my_timesheet_projects
unanet_get_company_info
unanet_get_billing_status
unanet_get_financial_report

Write-capable tools are gated behind a separate flag. Some are intentionally disabled or require confirmation until their Platform REST write flow is safe enough for routine use.

Quick install for Mac users

1. Install Node.js

Install Node.js 20 or newer from:

https://nodejs.org/

Choose the current LTS installer for macOS.

2. Download or clone this repo

If you use Git:

git clone https://github.com/navapbc/unanet-mcp-server.git
cd unanet-mcp-server

If you downloaded a ZIP, unzip it and open Terminal in the project folder.

3. Run the Mac setup script

./setup-mac.sh

The script will:

Check Node.js/npm.
Install dependencies.
Build the server.
Create a local .env file if needed.
Add this MCP server to Claude Desktop's config.

Your password stays in the local .env file. It is not written into Claude Desktop's config.

4. Restart Claude Desktop

Fully quit and reopen Claude Desktop.

Then ask Claude:

Show my Unanet leave balances.

If Claude can use the tool, the install worked.

Manual Mac install

Use this if you prefer to see each step.

1. Build the server

cd /Users/YOU/path/to/unanet-mcp-server
npm install
npm run build

2. Create `.env`

cp .env.example .env

Edit .env:

UNANET_BASE_URL=https://navapbc.unanet.biz
UNANET_USERNAME=your-username
UNANET_PASSWORD=your-password
UNANET_APP_NAME=NavaUnanetMCP

# Safe default: only the leave-balance tool is exposed.
UNANET_ENABLE_LEGACY_READ_TOOLS=false
UNANET_ENABLE_WRITE_TOOLS=false

To expose additional read tools:

UNANET_ENABLE_LEGACY_READ_TOOLS=true

To expose write-capable tools:

UNANET_ENABLE_WRITE_TOOLS=true

Only enable write tools when you intentionally want Claude to see them. Timesheet writes require confirm: true; several other legacy write tools still fail closed until they have safe Platform REST implementations.

3. Add the server to Claude Desktop

Edit:

~/Library/Application Support/Claude/claude_desktop_config.json

Add or merge this entry:

{
  "mcpServers": {
    "unanet": {
      "command": "/bin/bash",
      "args": [
        "-lc",
        "cd /absolute/path/to/unanet-mcp-server && node dist/index.js"
      ]
    }
  }
}

Why use bash -lc? The server loads .env from the project directory, so Claude needs to start it from that folder.

Restart Claude Desktop after changing the config.

Environment variables

Variable	Required	Default	Purpose
`UNANET_BASE_URL`	Yes	`https://navapbc.unanet.biz`	Unanet tenant origin. Do not include `/platform/rest`.
`UNANET_USERNAME`	Yes	—	Your Unanet username.
`UNANET_PASSWORD`	Yes	—	Your Unanet password.
`UNANET_APP_NAME`	No	`NavaUnanetMCP`	Value sent in the `X-Una-App` header.
`UNANET_ENABLE_LEGACY_READ_TOOLS`	No	`false`	Enables additional read tools/resources. Name is historical. These now use Platform REST bearer auth.
`UNANET_ENABLE_WRITE_TOOLS`	No	`false`	Enables mutating tools. Use carefully.
`UNANET_ALLOWED_BASE_URLS`	No	Nava tenant only	Comma-separated allow-list for additional production origins.
`UNANET_ALLOW_INSECURE_LOCAL_MOCK`	No	`false`	Allows `http://localhost` / `127.0.0.1` for local mock testing only.
`LOG_LEVEL`	No	`info`	Reserved for logging behavior.

Legacy UNANET_API_KEY and UNANET_FIRM_CODE are no longer needed for the Platform REST tools in this fork.

Tool surface

Default safe read tools

Tool	Description
`unanet_get_my_leave_balances`	Read your leave balances for a date range.
`unanet_get_my_expenses`	Read your expense reports and minimized line-item details.
`unanet_get_personal_development_fund_status`	Estimate personal/professional-development spending from expense reports; remaining balance is calculated only when a budget is provided.
`unanet_get_my_expense_report`	Read one expense report, optionally with validation.
`unanet_get_expense_reference_data`	Read expense types, payment methods, and currency codes needed to draft reports.
`unanet_validate_expense_report`	Validate a draft expense report without submitting it.
`unanet_get_expense_attachments`	List the receipt attachments on one of your expense reports (metadata only).

Additional read tools

Requires:

UNANET_ENABLE_LEGACY_READ_TOOLS=true

Tool	Description
`unanet_get_projects`	Search projects with optional filters.
`unanet_get_project_details`	Retrieve a project by key/id.
`unanet_get_project_status`	Retrieve project status-style summary data.
`unanet_get_timesheets`	Search your timesheets by date range, including entry-level timeslip summaries.
`unanet_get_my_timesheet_projects`	List projects available to charge on your timesheet for a given date.
`unanet_get_company_info`	Retrieve organization/company details.
`unanet_get_billing_status`	Retrieve billing-adjacent project invoice setup/account data.
`unanet_get_financial_report`	Limited invoice-search-backed financial reporting.

Write-capable tools

Requires:

UNANET_ENABLE_WRITE_TOOLS=true

Tool	Current behavior
`unanet_update_timesheet`	Live write; adds a time entry (one row per project/day) to your in-progress timesheet. Does not submit for approval, does not overwrite existing rows, and rejects a second entry for a project/day that already has one (use edit). Requires `confirm: true`.
`unanet_edit_timeslip`	Live write; changes the hours and/or comment of an existing entry in place. Identify by `timeslipKey`, or `projectId` + `date`; ambiguous matches return candidates instead of guessing. Requires `confirm: true`.
`unanet_delete_timeslip`	Live write; clears an entry (sets it to 0 hours and removes the comment). Unanet has no true row delete, so the project may still appear on the sheet with no hours. Requires `confirm: true`.
`unanet_submit_timesheet_for_approval`	Live write; validates the timesheet, then submits it for approval. Refuses on errors; holds on warnings unless `ignoreWarnings: true`. One-way action — requires `confirm: true`.
`unanet_create_expense_report_draft`	Live write; creates a draft expense report shell with explicit project allocations. Does not submit. Requires `confirm: true`.
`unanet_add_expense_detail`	Live write; adds one line item to a draft expense report using explicit expense type, payment method, currency, and wizard keys. Does not submit. Requires `confirm: true`.
`unanet_add_expense_attachment`	Live write; uploads a receipt to a draft report from a local `filePath` or inline base64 `data`, optionally associating it with a line via `detailId`. MIME type is inferred from the extension; 25 MB cap; `INUSE`-only. After uploading it reads the attachment list back and returns `verified: true/false` (Unanet's write responses are unreliable, so it confirms the file actually landed rather than trusting the POST). Does not submit. Requires `confirm: true`.
`unanet_update_project_budget`	Disabled/fail-closed; Platform REST requires a full project update payload.
`unanet_update_lead`	Disabled/fail-closed; no Platform REST lead endpoint identified.
`unanet_create_opportunity`	Disabled/fail-closed; no Platform REST opportunity endpoint identified.
`unanet_generate_invoice`	Disabled/fail-closed; no generic generate endpoint identified.
`unanet_approve_timesheet`	Live write; requires `confirm: true`.
`unanet_create_contact`	Live write; requires `confirm: true` and an organization id.

Architecture notes for maintainers

This fork uses two clients in src/auth.ts:

createPlatformRestClient — raw Platform REST client used for login and the leave tool.
createUnanetClient — Platform REST client that auto-prefixes /platform/rest, fetches/caches a bearer token, and adds Authorization: Bearer <token>.

Authentication flow:

POST /platform/rest/login
→ cache token in memory
→ call /platform/rest/... with Authorization: Bearer <token>

Security choices:

.env is ignored.
.env.test is no longer tracked.
Production base URLs must be HTTPS and allow-listed.
Local insecure mock URLs require explicit opt-in.
Tokens are cached in memory only.
Default Claude tool surface is read-only.

Development

npm install
npm run build
npm test
npm run mock-server

Project layout:

src/
├── index.ts              # MCP server entry point
├── auth.ts               # Platform REST auth, base URL validation, token cache
├── mock-server.ts        # Local mock Unanet API for tests
├── tools/
│   ├── leave.ts          # Default safe read-only leave-balance tool
│   ├── projects.ts       # Project tools
│   ├── timesheet.ts      # Timesheet/expense tools
│   ├── contacts.ts       # Organization/contact tools
│   └── financials.ts     # Billing/financial tools
├── resources/
│   └── reports.ts        # Optional MCP resources
└── types/
    └── unanet.ts         # Shared types

Troubleshooting

Claude does not show the Unanet tools

Fully quit and reopen Claude Desktop.
Confirm the server builds:
```
npm run build
```

Confirm the Claude config points at the right folder:

~/Library/Application Support/Claude/claude_desktop_config.json

Confirm .env exists in the project folder.

Authentication errors

Check:

UNANET_BASE_URL=https://navapbc.unanet.biz
UNANET_USERNAME is set
UNANET_PASSWORD is set
You can log into Unanet normally with the same credentials

Base URL rejected

The server intentionally rejects arbitrary production hosts. If you need another Unanet tenant, add it explicitly:

UNANET_ALLOWED_BASE_URLS=https://other-tenant.unanet.biz

Windows

This fork is primarily used on macOS at Nava. A Windows helper script still exists:

setup-windows.bat

It is best-effort and less exercised than the Mac setup path.

License

MIT License. See LICENSE for details.

Navigation Menu

Uh oh!

Unanet MCP Server for Claude Desktop

What works today

Quick install for Mac users

1. Install Node.js

2. Download or clone this repo

3. Run the Mac setup script

4. Restart Claude Desktop

Manual Mac install

1. Build the server

2. Create `.env`

3. Add the server to Claude Desktop

Environment variables

Tool surface

Default safe read tools

Additional read tools

Write-capable tools

Architecture notes for maintainers

Development

Troubleshooting

Claude does not show the Unanet tools

Authentication errors

Base URL rejected

Windows

License

Uh oh!

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

Unanet MCP Server for Claude Desktop

What works today

Quick install for Mac users

1. Install Node.js

2. Download or clone this repo

3. Run the Mac setup script

4. Restart Claude Desktop

Manual Mac install

1. Build the server

2. Create .env

3. Add the server to Claude Desktop

Environment variables

Tool surface

Default safe read tools

Additional read tools

Write-capable tools

Architecture notes for maintainers

Development

Troubleshooting

Claude does not show the Unanet tools

Authentication errors

Base URL rejected

Windows

License

2. Create `.env`