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.

1. 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