Metadata-Version: 2.5
Name: actionstep-mcp
Version: 0.2.0
Summary: MCP server for Actionstep API — full coverage for law firm practice management
Project-URL: Homepage, https://github.com/rosenadvertising/actionstep-mcp
Project-URL: Issues, https://github.com/rosenadvertising/actionstep-mcp/issues
License: MIT
License-File: LICENSE
Keywords: actionstep,claude,law,legal,mcp,practice-management
Requires-Python: >=3.10
Requires-Dist: keyring>=25.7.0
Requires-Dist: mcp<3,>=2.2
Requires-Dist: pydantic<3,>=2.13
Requires-Dist: requests>=2.34.2
Description-Content-Type: text/markdown

# actionstep-mcp

[![PyPI version](https://img.shields.io/pypi/v/actionstep-mcp.svg)](https://pypi.org/project/actionstep-mcp/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

MCP server for [Actionstep](https://actionstep.com) — 144 tools covering the full Actionstep REST API for law firm practice management. Use Actionstep from Claude Desktop with natural language.

## What you can do

- **Actions (Matters)** — create, update, assign, track workflow steps, manage billing settings
- **Participants (Contacts)** — full CRUD, relationships, contact notes, phone records
- **Tasks** — create, assign, complete, filter by matter or assignee
- **Time Records & Time Entries** — log time, manage billable entries, activity codes
- **Disbursements** — log expenses, link to matters
- **Calendar** — appointments linked to matters
- **Emails & SMS** — log communications, associate with matters
- **File Notes** — attendance notes and case notes on matters
- **Documents** — action documents and folders
- **Data Collections** — custom form data on matters
- **Webhooks** — REST hook subscriptions for real-time events
- **Reference data** — action types, participant types, rates, UTBMS codes, tax codes

## Requirements

- Python 3.10+
- Python MCP SDK >=2.2,<3 (the protocol target is 2026-07-28)
- Claude Desktop (or any MCP-compatible client)
- Actionstep developer credentials (Client ID, Client Secret)

> **Actionstep developer access:** Register at the Actionstep developer portal to obtain OAuth credentials.

## Installation

```bash
pip install actionstep-mcp
```

## Setup

```bash
actionstep-mcp-setup
```

This opens a browser for OAuth authorization and saves credentials to `~/.actionstep-mcp/`.

Verify:

```bash
actionstep-mcp-verify
```

## Claude Desktop Configuration

```json
{
  "mcpServers": {
    "actionstep": {
      "command": "actionstep-mcp"
    }
  }
}
```

## Credential storage

By default credentials are stored in your operating system's native secret store
via the cross-platform [`keyring`](https://github.com/jaraco/keyring) library:

| OS      | Backend                                  |
| ------- | ---------------------------------------- |
| macOS   | Keychain                                 |
| Windows | Credential Manager                       |
| Linux   | Secret Service (GNOME Keyring / KWallet) |

Secrets saved to keyring use the service name `actionstep-mcp`.

**File fallback.** On a host with no keyring backend (e.g. a headless Linux box
without Secret Service), or if you set `ACTIONSTEP_MCP_USE_KEYRING=0`, credentials
fall back to a `~/.actionstep-mcp/.env` file with `0600` permissions.

On Windows, the file is stored in the user's profile and protected by Windows'
default per-user access rules. On POSIX, files are created with `0600` permissions
and writes fail closed if private permissions cannot be established.

**Read order.** Credentials resolve in the order OS keyring → process environment
→ `.env` file. So a rotated secret in the keyring always wins, and an
`ACTIONSTEP_CLIENT_ID` / `ACTIONSTEP_CLIENT_SECRET` exported in your shell overrides
the file fallback without touching the keyring.

## Authentication Notes

Actionstep uses a dynamic `api_endpoint` — the URL for your organisation's API is returned in the OAuth token response and varies per firm. The setup wizard captures and stores this automatically.

## Example usage in Claude

> "List my open actions"
>
> "Create a task on action 456 — send retainer agreement to client"
>
> "Log 2.5 hours on action 789, description: drafted statement of claim"
>
> "Add a file note on action 123 — client called re: mediation date"
>
> "Create a calendar appointment for the Jones hearing on Monday 10am"

## License

MIT

<!-- ci-trigger 2026-05-27 -->

### Approved destination URLs

Set `ACTIONSTEP_ALLOWED_DESTINATION_HOSTS` in the server environment, for example
`ACTIONSTEP_ALLOWED_DESTINATION_HOSTS=hooks.firm.example,.integrations.firm.example`.
Comma-separated exact hosts allow only that host; a leading dot allows the domain
and its subdomains. Matching ignores case and trailing dots and normalizes IDNA.
An empty or unset list refuses destination URLs before any request. HTTPS, no
userinfo, and public literal addresses remain required. This administrator-owned
list prevents model-supplied destinations from sending data to arbitrary hosts,
including private-address DNS aliases and unapproved redirectors. Approve only
hosts whose DNS and redirects the firm trusts; the vendor executes requests later.
Tools cannot change this setting.

Configured API endpoints may use any host under `actionstep.com` or
`actionstepstaging.com`, including per-organization and regional hosts such as
`ap-southeast-2.actionstep.com` (or `actionstepstaging.com` for staging),
with no userinfo, query, fragment, or non-default port. Both an origin and the
vendor-returned `/api/` base are accepted. See the
[Actionstep authentication documentation](https://docs.actionstep.com/authentication).
