seven-mcp

seven-io/seven-mcp

3.2

If you are the rightful owner of seven-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

MCP Seven is a Model Context Protocol server for the seven.io API, offering access to SMS, voice, RCS messaging, and account management services.

Tools
5
Resources
0
Prompts
0

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