MCP Seven

Model Context Protocol (MCP) server for the seven.io API. This server provides comprehensive access to seven.io's SMS, voice, RCS messaging, and account management services.

Features

Messaging

SMS: Send and manage SMS messages
RCS: Send Rich Communication Services messages with media and suggestions
Voice: Send text-to-speech voice calls

Account Management

Balance: Check account balance
Pricing: Get pricing information by country
Analytics: View account statistics

Lookup Services

Format Validation: Validate phone number formats
HLR: Home Location Register lookups (network info, roaming status)
MNP: Mobile Number Portability lookups (carrier information)
CNAM: Caller ID name lookups
RCS Capabilities: Check if a number supports RCS

Contact Management

Contacts: Full CRUD operations for contacts
Groups: Manage contact groups

Phone Numbers

Browse, purchase, and manage phone numbers

Advanced Features

Webhooks: Register webhooks for events
Subaccounts: Create and manage subaccounts
Status & Logbook: Track message delivery and view history

Installation

npm install -g @seven.io/mcp

Authentication

This MCP server supports two authentication methods:

Option 1: OAuth 2.0 with PKCE (Recommended)

OAuth provides better security with automatic token refresh and fine-grained scopes.

Login via CLI:

npx @seven.io/mcp login

This will:

Open your browser to seven.io OAuth authorization
Request necessary permissions (SMS, Voice, RCS, etc.)
Store tokens securely in your system keychain
Auto-refresh tokens when they expire

CLI Commands:

# Login with OAuth
npx @seven.io/mcp login

# Check authentication status
npx @seven.io/mcp status

# Logout (remove stored tokens)
npx @seven.io/mcp logout

Option 2: API Key (Legacy)

For backwards compatibility, you can still use an API key:

export SEVEN_API_KEY="your-api-key"

Get your API key from the seven.io dashboard.

Priority

If both authentication methods are configured, OAuth takes priority.

Usage with Claude Desktop

Add this to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

Linux: ~/.config/Claude/claude_desktop_config.json

With OAuth (recommended):

{
  "mcpServers": {
    "seven": {
      "command": "npx",
      "args": ["@seven.io/mcp"]
    }
  }
}

With API Key:

{
  "mcpServers": {
    "seven": {
      "command": "npx",
      "args": ["@seven.io/mcp"],
      "env": {
        "SEVEN_API_KEY": "your-api-key"
      }
    }
  }
}

With Debug Logging: To enable request/response logging for debugging, add the SEVEN_LOG_FILE environment variable:

{
  "mcpServers": {
    "seven": {
      "command": "npx",
      "args": ["@seven.io/mcp"],
      "env": {
        "SEVEN_API_KEY": "your-api-key",
        "SEVEN_LOG_FILE": "/tmp/mcp-seven-debug.log"
      }
    }
  }
}

Then monitor the log file:

tail -f /tmp/mcp-seven-debug.log

Note: If using OAuth, run npx @seven.io/mcp login before starting Claude Desktop.

Available Tools

Messaging Tools

send_sms - Send SMS messages
delete_sms - Delete scheduled SMS
send_rcs - Send RCS messages
delete_rcs - Delete RCS messages
rcs_events - Handle RCS events
send_voice - Send voice calls
hangup_voice - End active voice calls

Account Tools

get_balance - Check account balance
get_pricing - Get pricing information
get_analytics - View account statistics

Lookup Tools

lookup_format - Validate phone number format
lookup_hlr - Home Location Register lookup
lookup_mnp - Mobile Number Portability lookup
lookup_cnam - Caller ID name lookup
lookup_rcs - Check RCS capabilities

Status & Logbook Tools

get_status - Check message delivery status
get_logbook_sent - View sent messages
get_logbook_received - View received SMS
get_logbook_voice - View voice call history

Phone Numbers Tools

get_available_numbers - List available numbers
order_number - Purchase a phone number
get_active_numbers - List active numbers
get_number - Get number details
update_number - Update number configuration
delete_number - Cancel/delete number

Contact Tools

list_contacts - List all contacts
create_contact - Create new contact
get_contact - Get contact by ID
update_contact - Update contact
delete_contact - Delete contact

Group Tools

list_groups - List all groups
create_group - Create new group
get_group - Get group by ID
update_group - Update group
delete_group - Delete group

Subaccount Tools

list_subaccounts - List all subaccounts
create_subaccount - Create new subaccount
update_subaccount - Update subaccount settings
transfer_credits - Transfer credits to subaccount
delete_subaccount - Delete subaccount

Webhook Tools

list_webhooks - List registered webhooks
create_webhook - Register new webhook
delete_webhook - Delete webhook

Sender Tools

validate_sender - Validate sender identifiers

Example Usage

Once configured, you can use the tools in Claude:

Send an SMS to +1234567890 saying "Hello from seven.io!"

Check my account balance

Look up the carrier information for phone number +1234567890

Development

Watch mode

npm run watch

Build

npm run build

Testing

Run the comprehensive test suite:

npm test

Run tests in watch mode:

npm run test:watch

Generate coverage report:

npm run test:coverage

Test Coverage

The test suite includes:

Unit tests for all API client methods
Tool tests for all 40+ MCP tools covering:
- RCS messaging (3 tools)
- SMS messaging (2 tools)
- Voice calls (2 tools)
- Account management (3 tools)
- Lookup services (5 tools)
- Status & Logbook (4 tools)
- Phone number management (6 tools)
- Contact management (5 tools)
- Group management (5 tools)
- Subaccount management (5 tools)
- Webhook management (3 tools)
- Sender validation (1 tool)
Integration tests verifying all tools export correctly and have valid schemas
Endpoint validation tests that verify API endpoint paths are correct (requires SEVEN_API_KEY)

Coverage target: 80% for branches, functions, lines, and statements.

Endpoint Validation

To run endpoint validation tests that verify the API paths are correct:

SEVEN_API_KEY=your-api-key npm test

These integration tests ensure that endpoints match the seven.io API documentation and will catch issues like incorrect paths (e.g., using /logbook/received instead of /journal/inbound).

API Documentation

For detailed API documentation, visit docs.seven.io.

License

MIT