Docs · Beta for invited accounts
HitDM MCP server
By Amit Dobal, founder of HitDMUpdated
The HitDM MCP server lets an AI app read a workspace's automations, stats, posts and contacts, and make a few reviewable changes. It never sends a DM. Setup steps for Claude, ChatGPT and Cursor are on the AI assistants page.
- 11tools: 7 read, 4 change
- 5permissions, each listed below
- 10items per list page, 25 at most
Server and sign-in
- URL:
https://mcp.hitdm.com/mcp, transport Streamable HTTP. - Sign-in: OAuth 2.1 with PKCE and dynamic client registration. No API keys, nothing secret in the URL.
- The person signs in with Google on hitdm.com, picks one workspace and the permissions, then allows the app. One connection covers one workspace.
- Apps HitDM cannot verify are labelled on the consent screen and never get the two extra permissions below.
- Disconnect any time in Settings, Connected apps.
Permissions
| Permission | What it allows | Needs |
|---|---|---|
hitdm:read | Read automations, stats, posts, contacts and usage. Always granted. | Every plan |
hitdm:write | Paused drafts, pauses and DM edits on paused automations. | Paid plans |
contacts:pii | Unmasked contact email and phone numbers. | Owner switch Full contact details, verified apps only |
automations:activate | Turn automations on and edit live ones. The owner is emailed each time. | Owner switch, paid plans, verified apps only |
offline_access | Refresh tokens, so the app stays connected. | Optional |
Tools
Seven read tools and four change tools. List tools return 10 items by default and at most 25; pass next_cursor for the next page. Text other people wrote (names, captions, keywords) comes back under an untrusted object. Responses never carry Instagram account IDs, tokens or permalinks.
Read
| Tool | Title | What it returns | Hint |
|---|---|---|---|
get_account | Get account | Plan, workspace name, connected Instagram accounts (handle and status) and today's AI assistant usage. Call it first. | Read only |
get_plan_usage | Get plan usage | DMs used this month against the plan, and today's AI assistant usage against its daily limits. | Read only |
list_automations | List automations | Automations, most recently changed first, with DMs sent and link taps. Paged. | Read only |
get_automation | Get automation | One automation in full: trigger, keywords, post scope, DM message and link, follow-up and Growth Gate settings. | Read only |
get_automation_stats | Get automation stats | Sends, link taps and tap rate for one automation, with a daily series for the last 7 or 14 days. | Read only |
list_recent_posts | List recent posts | Recent posts and reels for one Instagram account, each with an opaque handle a draft can point at. Captions are cut to 280 characters. | Read only |
list_contacts | List contacts | People who commented, replied or tapped a link, most recent first. Email and phone are masked unless the owner allowed full contact details. Paged. | Read only |
Change
Every change takes an optional idempotency_key, so a retry never makes a second change. The owner is notified about pauses and turn-ons.
| Tool | Title | What it does | Hint |
|---|---|---|---|
create_automation | Create paused automation | Creates a comment-keyword automation as a paused draft and returns a review link for the owner. It sends nothing. | Change, not destructive |
pause_automation | Pause automation | Pauses one automation and cancels its queued DMs. The owner gets a notice with a one-click Resume. | Change, not destructive |
activate_automation | Turn automation on | Turns one paused automation on, only when the owner allowed it. Otherwise it answers activation_disabled with a review link. | Change, not destructive |
update_dm_message | Edit DM message | Edits the DM text and optionally the link. Paused automations always; live ones only when the owner allowed it. | Change, not destructive |
Errors and limits
| Code | Meaning |
|---|---|
insufficient_scope | The connection was not given the permission this tool needs. Reconnect and allow it. |
activation_disabled | The owner has not allowed AI assistants to turn automations on. The answer carries a review link for the dashboard. |
cap_reached | A daily limit is used up. The answer says when it resets (00:00 UTC) and links to plans. Reads stay on when only changes are capped. |
grant_revoked | The owner disconnected the app in Settings, Connected apps. Sign in again to reconnect. |
invalid_input | An argument failed validation. The message names the field. |
not_found | The automation or post is not in the connected workspace. |
in_progress | The same change is still running. Retry in a few seconds with the same idempotency key. |
- Daily limits per plan (tool calls, changes, contact rows, connected apps) are in the Terms. They reset at 00:00 UTC.
- Past the daily request limit the server answers HTTP 429 with a Retry-After header until the reset. Short bursts get 429 too.
- AI assistant limits never pause comment-to-DM automations and do not count toward the DM allowance.
