# Moxie MCP Server v2

Upgraded MCP server for [Moxie CRM](https://withmoxie.com) — fully compatible with **Claude Desktop**, **Claude Code**, **Osaurus**, **Cursor**, **VS Code Cline**, and any MCP client.

## Upgrades from v1.1.x

- **Claude JSON compatible** — works with `claude_desktop_config.json` out of the box
- **`dotenv` support** — load config from `.env` file for local dev
- **MCP Resources** — exposes workspace config and server info as resources
- **Health check tool** (`moxie_health_check`) — validate your setup
- **Startup validation** — warns on missing env vars at launch
- **Renamed binary** — `moxie-mcp` (shorter, cleaner)
- **Updated dependencies** — latest `@modelcontextprotocol/sdk`, `axios`, `zod`

## Quick Start

```bash
git clone <your-repo-url> moxie-mcp
cd moxie-mcp
npm install
npm run build
```

### Get Your API Key

1. Log into your [Moxie](https://withmoxie.com) account
2. **Workspace Settings** → **Connected Apps** → **Integrations**
3. Click **Enable Custom Integration**
4. Copy your **API Key** and **Base Endpoint URL**

## Claude JSON Config (Claude Desktop / Osaurus / Any MCP Client)

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "moxie": {
      "command": "node",
      "args": ["/absolute/path/to/moxie-mcp/build/index.js"],
      "env": {
        "MOXIE_API_KEY": "your_api_key_here",
        "MOXIE_BASE_URL": "https://pod01.withmoxie.com/api/public"
      }
    }
  }
}
```

For **Osaurus** or **OpenRouter** MCP configs, use the same structure.

### Or install globally and use `npx`:

```json
{
  "mcpServers": {
    "moxie": {
      "command": "npx",
      "args": ["-y", "moxie-mcp"],
      "env": {
        "MOXIE_API_KEY": "your_api_key_here",
        "MOXIE_BASE_URL": "https://pod01.withmoxie.com/api/public"
      }
    }
  }
}
```

## Resources

This server exposes MCP resources for context-aware clients:

| Resource URI | Description |
|---|---|
| `moxie://workspace/config` | Workspace configuration details |
| `moxie://server/info` | Server version and available tools |

## Available Tools

### Clients
- `list_clients` — List all clients
- `search_clients` — Search clients by name/contact
- `create_client` — Create a new client

### Contacts
- `search_contacts` — Search contacts by name/email/phone
- `create_contact` — Create a contact under a client

### Projects
- `search_projects` — Search projects (optionally by client)
- `create_project` — Create a project
- `update_project` — Update project details
- `list_project_task_stages` — List kanban stages

### Invoices
- `search_payable_invoices` — Search invoices
- `create_invoice` — Create invoice (draft or send)
- `apply_payment` — Apply payment to invoice

### Tasks
- `create_task` — Create task with subtasks, assignees, custom fields

### Time Tracking
- `create_time_entry` — Log time with auto-creation flags

### Expenses
- `create_expense` — Record expenses (billable/reimbursable)

### Sales Pipeline
- `list_pipeline_stages` — List pipeline stages
- `create_opportunity` — Create opportunity

### Support Tickets
- `create_ticket` — Create ticket with structured form data
- `create_ticket_comment` — Add comment to ticket

### Forms
- `list_form_names` — List forms
- `create_form_submission` — Submit lead form (optionally create opportunity)

### Files
- `attach_file_from_url` — Attach file from URL to any entity

### Calendar
- `create_or_update_calendar_event` — Create or update an event
- `delete_calendar_event` — Delete event

### Deliverables
- `approve_deliverable` — Approve a task/deliverable

### Reference
- `list_email_templates` — List email templates
- `list_invoice_templates` — List invoice templates
- `list_vendor_names` — List expense vendors
- `list_workspace_users` — List workspace users

### Diagnostics
- `moxie_health_check` — Verify server and API connectivity

## Configuration

| Variable | Required | Description |
|---|---|---|
| `MOXIE_API_KEY` | Yes | Your Moxie API key |
| `MOXIE_BASE_URL` | Yes | Your Moxie API base URL |

## Development

```bash
# Watch mode
npm run dev

# Build
npm run build

# Test with MCP Inspector
MOXIE_API_KEY=your_key MOXIE_BASE_URL=your_url npx @modelcontextprotocol/inspector node build/index.js
```

## License

MIT