@jclvsh/iris

v0.10.0

Published

3 days ago

MCP server for the Iris API

0High
0Medium
0Low

@jclvsh/iris

MCP server and CLI for the Iris API — AI-powered messaging assistant for automated multi-channel outreach campaigns. Lets AI agents (Claude Code, Cursor) and humans manage campaigns, contacts, conversations, AI generations, discovery, channels, and webhooks.

Installation

npm install -g @jclvsh/iris

This installs two binaries:

iris — CLI for terminal use
iris-mcp — MCP server for AI agents

Or run one-shot without installing:

npx -y -p @jclvsh/iris iris-mcp

CLI

# set your API key
export IRIS_API_KEY=is_live_...

# manage campaigns
iris campaigns list
iris campaigns create -n "spring outreach" -o product_promotion --product-name "acme widgets"
iris campaigns analyze <id>
iris campaigns usage <id>

# manage contacts
iris contacts list --campaign-id <id>
iris contacts create --campaign-id <id> -e [email protected] --full-name "Jane Doe" --company-name "Acme"

# review the AI approval queue
iris messages pending --campaign-id <id>
iris messages approve <id>
iris messages reject <id> --reason "off-topic"
iris messages bulk -a approve --ids id1,id2,id3

# manage webhooks
iris webhooks create -u https://example.com/hook -e campaign.created,message.delivered
iris webhooks test <id>
iris webhooks deliveries <id>

# check your key
iris keys me

# table output
iris --format table campaigns list

# full help
iris --help
iris campaigns --help

CLI Commands

| Group | Alias | Commands | Count | | ------------- | ------ | ------------------------------------------------------------- | ----- | | campaigns | c | list, get, create, update, delete, usage, analyze | 7 | | contacts | ct | list, get, create, update, delete, usage | 6 | | messages | m | pending, approve, reject, retry, feedback, bulk | 6 | | conversations | conv | list, get, messages, read | 4 | | discovery | d | search, search-campaign, sources, job | 4 | | ai | — | generate, generate-campaign, analyze, usage | 4 | | keys | k | me, list, create, rename, revoke | 5 | | webhooks | w | list, create, get, update, delete, test, deliveries | 7 | | notifications | n | list, update, delete, read-all | 4 | | analytics | a | overview, campaign, performance, response-time, contact-types | 5 | | billing | b | plans | 1 | | channels | ch | accounts, availability, send | 3 | | credits | cr | balance, buy | 2 |

MCP Server Configuration

Environment Variables

| Variable | Required | Description | | -------------- | -------- | ---------------------------------------------------- | | IRIS_API_KEY | Yes | API key (must start with is_live_) | | IRIS_API_URL | No | API base URL (default: https://iris-ai.dev/api/v1) |

Note: the args use -p @jclvsh/iris iris-mcp to explicitly select the MCP-server bin. The package ships two binaries (iris for the CLI, iris-mcp for the MCP server), so a bare npx @jclvsh/iris would launch the CLI by default.

Get your API key at iris-ai.dev/settings/api-keys.

Claude Code

Add to your .claude/settings.json:

{
	"mcpServers": {
		"iris": {
			"command": "npx",
			"args": ["-y", "-p", "@jclvsh/iris", "iris-mcp"],
			"env": {
				"IRIS_API_KEY": "is_live_your_key_here"
			}
		}
	}
}

Cursor

Add to .cursor/mcp.json:

{
	"mcpServers": {
		"iris": {
			"command": "npx",
			"args": ["-y", "-p", "@jclvsh/iris", "iris-mcp"],
			"env": {
				"IRIS_API_KEY": "is_live_your_key_here"
			}
		}
	}
}

Available Tools

Campaigns

| Tool | Description | | ------------------------ | ------------------------------------------------------- | | list_campaigns | List campaigns with optional status filter | | create_campaign | Create a new outreach campaign | | get_campaign | Get a campaign by ID with stats | | update_campaign | Update a campaign's name, status, or follow-up settings | | delete_campaign | Soft-delete a campaign (sets status to deleted) | | list_campaign_contacts | List contacts in a campaign with optional status filter | | get_campaign_usage | Get usage limits and current counts for a campaign | | analyze_campaign | Trigger AI analysis to generate target profiles | | list_target_profiles | List target profiles for a campaign | | create_target_profile | Create a target profile for a campaign | | delete_target_profile | Delete a target profile from a campaign |

`create_campaign` Parameters

| Parameter | Type | Required | Description | | --------------------- | -------------- | -------- | ------------------------------------------------------- | | name | string (1-100) | Yes | Campaign name | | objective_type | enum | Yes | venue_dj, venue_host, product_promotion, custom | | product_name | string (≤200) | No | Product name (for product_promotion) | | product_url | string (URL) | No | Product URL (for product_promotion) | | product_description | string (≤2000) | No | Product description (for product_promotion) |

`update_campaign` Parameters

| Parameter | Type | Required | Description | | ---------------------- | -------------- | -------- | --------------------------------------------------- | | id | string (UUID) | Yes | Campaign ID | | name | string (1-100) | No | New campaign name | | status | enum | No | draft, active, paused, completed, deleted | | follow_up_enabled | boolean | No | Enable follow-up emails | | follow_up_max_count | number (0-10) | No | Max follow-up count | | follow_up_delay_days | number (1-30) | No | Days between follow-ups |

`create_target_profile` Parameters

| Parameter | Type | Required | Description | | ---------------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------- | | id | string (UUID) | Yes | Campaign ID | | name | string (1-200) | Yes | Profile name | | profile_type | enum | Yes | local_business, content_creator, influencer, b2b_professional, ecommerce, saas_company, agency, freelancer, other | | job_titles | string[] | No | Target job titles | | industries | string[] | No | Target industries | | discovery_keywords | string[] | No | Keywords for contact discovery | | recommended_channels | string[] | No | email, instagram, twitter, linkedin |

Contacts

| Tool | Description | | ---------------------------- | ----------------------------------------- | | list_contacts | List contacts with search | | create_contact | Create a new contact | | get_contact | Get a contact by ID | | update_contact | Update a contact's details | | delete_contact | Soft-delete a contact | | bulk_import_contacts | Import up to 500 contacts at once | | get_contact_usage | Get usage limits for the billing period | | list_contact_conversations | List conversations for a specific contact |

`create_contact` Parameters

| Parameter | Type | Required | Description | | -------------- | -------------- | -------- | ----------------------- | | email | string (email) | Yes | Contact email address | | first_name | string (≤100) | No | First name | | last_name | string (≤100) | No | Last name | | company_name | string (≤200) | No | Company name | | job_title | string (≤200) | No | Job title | | phone | string (≤50) | No | Phone number | | website | string (URL) | No | Website URL | | tags | string[] | No | Tags for categorization |

`bulk_import_contacts` Parameters

| Parameter | Type | Required | Description | | ------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------ | | contacts | object[] (1-500) | Yes | Array of contacts (email, first_name?, last_name?, company_name?, job_title?, tags?) | | campaign_id | string (UUID) | No | Campaign to add contacts to |

Messages

| Tool | Description | | ------------------------- | ------------------------------------------------ | | list_pending_messages | List messages pending approval | | approve_message | Approve a single pending message | | reject_message | Reject a single pending message | | retry_message | Retry a failed message send | | submit_message_feedback | Submit feedback to improve future AI generations | | bulk_message_action | Bulk approve or reject pending messages |

Conversations

| Tool | Description | | --------------------------- | ------------------------------------------------------- | | list_conversations | List conversations with optional channel/status filters | | get_conversation | Get a conversation by ID | | get_conversation_messages | List messages in a conversation | | mark_conversation_read | Mark a conversation as read | | get_engagement_metrics | Get engagement metrics across conversations |

AI

| Tool | Description | | --------------------------- | -------------------------------------------------------------------------------- | | generate_content | Generate AI content for a contact conversation (initial email, follow-up, reply) | | generate_campaign_content | Generate campaign-level content (email templates, subject lines, briefs) | | analyze_response | Analyze inbound message sentiment, intent, and suggested action | | get_ai_usage | Get AI generation usage limits |

`generate_content` Parameters

| Parameter | Type | Required | Description | | ----------------- | -------------- | -------- | ------------------------------------- | | contact_id | string (UUID) | Yes | Contact ID | | conversation_id | string (UUID) | Yes | Conversation ID | | generation_type | enum | Yes | initial_email, follow_up, reply | | context | string (≤2000) | No | Additional context for the AI |

Discovery

| Tool | Description | | -------------------------- | ------------------------------------------------------------- | | search_contacts | Search for contacts by criteria (location, keywords, sources) | | search_campaign_contacts | Run discovery scoped to a campaign's target profiles | | get_discovery_job | Get the status of a discovery job | | list_discovery_sources | List available discovery sources (Google Maps, social) |

Channels

| Tool | Description | | ---------------------------- | ------------------------------------------------------------------ | | list_connected_accounts | List your connected social accounts (Twitter, Instagram, LinkedIn) | | check_channel_availability | Check which channels are reachable for a contact | | send_channel_message | Send a message via a specific channel |

Analytics

| Tool | Description | | ------------------------- | -------------------------------------- | | get_analytics_overview | Account-level analytics overview | | get_campaign_analytics | Per-campaign performance metrics | | get_performance_metrics | Aggregate performance across campaigns | | get_response_time | Response time distribution | | get_contact_types | Engagement broken down by contact type |

Notifications

| Tool | Description | | ----------------------------- | ----------------------------------------------- | | list_notifications | List your notifications | | update_notification | Mark a notification as read or update its state | | delete_notification | Delete a notification | | mark_all_notifications_read | Mark every unread notification as read |

Billing

| Tool | Description | | ------------------- | --------------------------------- | | get_billing_plans | List available subscription plans |

API Keys

| Tool | Description | | --------------------- | ------------------------------------------------- | | get_current_api_key | Get details about the currently authenticated key | | list_api_keys | List all API keys for the account | | create_api_key | Create a new API key (raw key returned once) | | revoke_api_key | Revoke (delete) an API key |

`create_api_key` Parameters

| Parameter | Type | Required | Description | | ------------ | ----------------- | -------- | --------------------------------------------------------------------------- | | name | string (1-100) | Yes | Key name for identification | | scopes | string[] | No | Permission scopes (defaults to all scopes) — see Scopes | | expires_at | string (ISO 8601) | No | Expiration date |

Webhooks

| Tool | Description | | ------------------------- | ---------------------------------------------------- | | list_webhooks | List all configured webhooks | | create_webhook | Create a new webhook endpoint | | get_webhook | Get a webhook by ID | | update_webhook | Update a webhook's URL, events, or active status | | delete_webhook | Delete a webhook | | test_webhook | Send a test event to a webhook URL | | rotate_webhook_secret | Rotate the signing secret (new secret returned once) | | list_webhook_deliveries | List delivery history for a webhook |

`create_webhook` Parameters

| Parameter | Type | Required | Description | | ------------- | ------------------ | -------- | -------------------------------------------------------------- | | url | string (HTTPS URL) | Yes | Webhook endpoint URL — HTTPS only | | events | string[] (≥1) | Yes | Events to subscribe to — see Webhook Events | | description | string (≤500) | No | Webhook description |

`update_webhook` Parameters

| Parameter | Type | Required | Description | | --------- | ------------------ | -------- | ----------------------------- | | id | string (UUID) | Yes | Webhook ID | | url | string (HTTPS URL) | No | New endpoint URL | | events | string[] (≥1) | No | New events to subscribe to | | active | boolean | No | Enable or disable the webhook |

Agent Credits

Credits apply only to agents authenticating via x402 (USDC on Base) or MPP (Stripe). API key users do not need credits.

| Tool | Description | | ---------------------- | ----------------------------------------- | | get_credit_balance | Check the agent credit balance | | purchase_credit_pack | Purchase a 5-credit pack via MPP ($12.00) |

API Key & Scopes

Generate an API key at iris-ai.dev/settings/api-keys.

API keys support fine-grained scopes per resource:

| Scope | Access | | -------------------------------------------- | -------------------------------------------- | | campaigns:read / campaigns:write | Read or modify campaigns | | contacts:read / contacts:write | Read or modify contacts | | conversations:read / conversations:write | Read conversations or send messages | | messages:read / messages:write | Read the queue, approve/reject/send | | ai:read / ai:write | Read AI usage or trigger generations | | discovery:read / discovery:write | Read sources or run discovery jobs | | analytics:read | Read analytics dashboards | | billing:read | Read billing plans | | channels:read / channels:write | Read connected accounts or send via channels | | notifications:read / notifications:write | Read or modify notifications | | webhooks:read / webhooks:write | Read or manage webhook subscriptions | | keys:read / keys:write | Read or manage API keys |

Recommended Scopes by Use Case

| Use Case | Recommended Scopes | | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | AI agents / MCP | campaigns:read, campaigns:write, contacts:read, contacts:write, messages:read, messages:write, ai:read, ai:write, conversations:read, conversations:write | | Read-only monitoring | *:read scopes only | | Webhook management | webhooks:read, webhooks:write | | Discovery automation | discovery:read, discovery:write, contacts:write, campaigns:read |

Webhook Events

| Event | Description | | ----------------------------- | ----------------------------------- | | campaign.created | New campaign created | | campaign.updated | Campaign details changed | | campaign.deleted | Campaign soft-deleted | | contact.created | New contact added | | contact.updated | Contact details changed | | contact.deleted | Contact soft-deleted | | conversation.created | New conversation started | | conversation.reply_received | Inbound reply received | | message.sent | Outbound message sent | | message.delivered | Message confirmed delivered | | message.opened | Email opened (filtered for bots) | | message.bounced | Message bounced | | message.approved | Message approved in the queue | | message.rejected | Message rejected in the queue | | discovery.completed | Discovery job finished successfully | | discovery.failed | Discovery job failed |

Webhook deliveries are signed with HMAC-SHA256 using the secret returned from create_webhook / rotate_webhook_secret. Verify the signature in the X-Iris-Signature header before trusting the payload.

Documentation

Full API reference: iris-ai.dev/docs

Development

# install dependencies
npm install

# build
npm run build

# run the MCP server
IRIS_API_KEY=is_live_... npm start

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@jclvsh/iris

Installation

CLI

CLI Commands

MCP Server Configuration

Environment Variables

Claude Code

Cursor

Available Tools

Campaigns

create_campaign Parameters

update_campaign Parameters

create_target_profile Parameters

Contacts

create_contact Parameters

bulk_import_contacts Parameters

Messages

Conversations

AI

generate_content Parameters

Discovery

Channels

Analytics

Notifications

Billing

API Keys

create_api_key Parameters

Webhooks

create_webhook Parameters

update_webhook Parameters

Agent Credits

API Key & Scopes

Recommended Scopes by Use Case

Webhook Events

Documentation

Development

`create_campaign` Parameters

`update_campaign` Parameters

`create_target_profile` Parameters

`create_contact` Parameters

`bulk_import_contacts` Parameters

`generate_content` Parameters

`create_api_key` Parameters

`create_webhook` Parameters

`update_webhook` Parameters