npm package: @practicestack/mcp-server
Description: MCP server for PracticeStacks — manage proposals, leads, contacts, compliance, and more from Claude
Latest version: 1.0.9

# @practicestack/mcp-server

MCP (Model Context Protocol) server for [PracticeStacks](https://www.practicestacks.in) — manage your entire practice management platform from Claude.

Exposes **42 tools** across proposals, leads, contacts, businesses, compliance, employees, departments, services, statistics, and settings.

## Quick Start

### Claude.ai (Web)

1. Go to **Claude.ai** > **Settings** > **Connectors** > **Add custom connector**
2. Enter:
   - **Name**: `PracticeStacks`
   - **URL**: `https://www.practicestacks.in/mcp`
3. Click **Add** — Claude.ai will redirect you to PracticeStacks to log in and approve
4. Done. All 42 tools are now available in Claude.ai conversations.

### Claude Code

```bash
npx @practicestack/mcp-server
```

The server auto-opens your browser for authentication on first run. Log in to PracticeStacks, click **Approve**, and you're connected. Credentials are saved to `~/.practicestack/credentials.json` for future sessions.

### Claude Desktop

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "practice-stack": {
      "command": "npx",
      "args": ["-y", "@practicestack/mcp-server"]
    }
  }
}
```

### Claude Code (`.mcp.json`)

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "practice-stack": {
      "command": "npx",
      "args": ["-y", "@practicestack/mcp-server"]
    }
  }
}
```

## Authentication

Authentication is automatic. On first run, the server:

1. Checks for `PRACTICESTACK_API_TOKEN` environment variable
2. Checks for saved credentials at `~/.practicestack/credentials.json`
3. Opens your browser to authorize the connection (zero-config)

### Using an API Token (optional)

If you prefer manual setup, create an API token in **PracticeStacks > Settings > API Tokens**, then:

```bash
PRACTICESTACK_API_TOKEN=ps_live_xxxxx npx @practicestack/mcp-server
```

Or in your MCP config:

```json
{
  "mcpServers": {
    "practice-stack": {
      "command": "npx",
      "args": ["-y", "@practicestack/mcp-server"],
      "env": {
        "PRACTICESTACK_API_TOKEN": "ps_live_xxxxx"
      }
    }
  }
}
```

## Environment Variables

| Variable | Default | Description |
|----------|---------|-------------|
| `PRACTICESTACK_API_TOKEN` | — | Skip browser auth with an explicit API token |
| `PRACTICESTACK_API_URL` | `https://www.practicestacks.in` | Override the API base URL |

## Available Tools (42)

### Proposals (4 tools)

| Tool | Description |
|------|-------------|
| `list-proposals` | List all proposals with status, value, business, and dates |
| `get-proposal` | Get full proposal details including services, packages, and testimonials |
| `update-proposal` | Update title, status, cover letter, scope, terms, value, currency, or expiry |
| `send-proposal-notification` | Send email/WhatsApp notification to the client |

### Leads (5 tools)

| Tool | Description |
|------|-------------|
| `list-leads` | List leads with filters for status, priority, source, and search |
| `create-lead` | Create a new lead with company details and tracking metadata |
| `update-lead` | Update lead details, status, or priority |
| `delete-lead` | Permanently delete a lead |
| `convert-lead` | Convert a qualified lead into a business/client |

### Businesses (4 tools)

| Tool | Description |
|------|-------------|
| `list-businesses` | List all businesses/clients |
| `get-business` | Get detailed business info including contacts and compliance |
| `update-business` | Update name, contact info, GST, branding, or templates |
| `list-business-proposals` | List all proposals for a specific business |
| `list-business-compliance` | List compliance records for a specific business |

### Contacts (5 tools)

| Tool | Description |
|------|-------------|
| `list-contacts` | List all contacts across all businesses |
| `list-business-contacts` | List contacts for a specific business |
| `create-contact` | Create a new contact under a business |
| `update-contact` | Update contact details, title, or set as primary |
| `delete-contact` | Delete a contact |

### Compliance (4 tools)

| Tool | Description |
|------|-------------|
| `list-compliance` | List all compliance/filing records with due dates and statuses |
| `get-compliance` | Get detailed compliance record with history and documents |
| `list-compliance-types` | List available compliance types (GST, TDS, ITR, ROC, etc.) |
| `get-compliance-report` | Generate compliance statistics and completion rates |

### Employees (4 tools)

| Tool | Description |
|------|-------------|
| `list-employees` | List all team members with positions and departments |
| `create-employee` | Add a new employee (requires available subscription seat) |
| `update-employee` | Update employee profile, position, or module access |
| `delete-employee` | Remove an employee (frees subscription seat) |

### Departments (3 tools)

| Tool | Description |
|------|-------------|
| `list-departments` | List all departments |
| `create-department` | Create a new department |
| `delete-department` | Delete a department |

### Services (2 tools)

| Tool | Description |
|------|-------------|
| `list-services` | List all services with pricing, billing type, and tax rates |
| `list-service-packages` | List service packages (bundles of multiple services) |

### Statistics (6 tools)

| Tool | Description |
|------|-------------|
| `get-dashboard-stats` | High-level stats: proposals, revenue, clients, compliance trends |
| `get-revenue-pipeline` | Revenue breakdown by status, monthly trends, and projections |
| `get-proposals-overview` | Proposal status distribution, conversion rates, and averages |
| `get-compliance-deadlines` | Upcoming deadlines, overdue items, and deadline calendar |
| `get-expiring-proposals` | Proposals expiring within N days (default: 30) |
| `get-recent-proposals` | Most recently created or updated proposals |

### Settings (5 tools)

| Tool | Description |
|------|-------------|
| `get-user-profile` | Get your profile: name, email, phone, role, business details |
| `update-user-profile` | Update your name, designation, or address |
| `get-business-settings` | Get branding, templates, and signature preferences |
| `get-subscription` | Get subscription plan, seat count, and billing status |
| `get-audit-logs` | Recent audit logs — who did what and when |

## Example Usage

Once connected, just ask Claude naturally:

- *"Show me all pending proposals"*
- *"Create a lead for Acme Corp from LinkedIn, high priority"*
- *"What compliance deadlines are coming up this week?"*
- *"Convert the Acme Corp lead to a business"*
- *"Send a notification for proposal XYZ"*
- *"Show my dashboard stats"*
- *"List all employees in the Audit department"*

## Requirements

- Node.js 20+
- A [PracticeStacks](https://www.practicestacks.in) account

## License

MIT