Vitally MCP Server

An MCP (Model Context Protocol) server that provides access to Vitally customer data via the Vitally API.

Containerized

If you need a containerized version, check out github.com/fiscaltec/vitally-mcp

Features

• List customer accounts as resources

• Read account details

• Search for users by email or external ID

• Find accounts by name

• Query account health scores

• View account conversations and tasks

• Create notes for accounts

• Search through available tools

• Demo mode with mock data when no API key is provided

Setup

1. Install dependencies:

   npm install

2. Create a .env file in the root directory with the following:

   # Vitally API Configuration VITALLY_API_SUBDOMAIN=nylas # Your Vitally subdomain VITALLY_API_KEY=your_api_key_here # Your Vitally API key VITALLY_DATA_CENTER=US # or EU depending on your data center

3. Build the project:

   npm run build

Note: If you don't have a Vitally API key yet, the server will run in demo mode with mock data.

Getting your Vitally API Key

1. Navigate to your Vitally account

2. Go to Settings (⚙️) > Integrations > REST API

3. Toggle the switch to enable the integration

4. Copy the API Key

Usage

There are two ways to use this MCP server:

Using the MCP Inspector

Run the MCP Inspector to test and debug the server:

This will open the MCP Inspector interface where you can interact with your server.

Connect to Claude Desktop

1. First, find your Claude Desktop configuration file:

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

   • On Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Edit the config file to add the Vitally MCP server:

   { "mcpServers": { "vitally-api": { "command": "node", "args": ["--experimental-modules", "--experimental-specifier-resolution=node", "/Users/johnjung/nylas/vitally/vitally/build/index.js"] } } }

3. Restart Claude Desktop and you'll be able to use the Vitally MCP server.

Available Tools

Tool Discovery

• search_tools - Search for available tools by keyword

Account Management

• search_accounts - Search for accounts using multiple criteria (name, externalId)

• find_account_by_name - Find accounts by their name (partial matching supported)

• refresh_accounts - Refresh the cached list of accounts

• get_account_health - Get health scores for a specific account

User Management

• search_users - Search for users by email, external ID, or email subdomain

Communication & Tasks

• get_account_conversations - Get recent conversations for an account

• get_account_tasks - Get tasks for an account (can filter by status)

• create_account_note - Create a new note for an account

Example Questions to Ask

When connected to an MCP client like Claude, you can ask questions such as:

• "List all our customers"

• "Find accounts with 'Acme' in their name"

• "What's the health score for account X?"

• "Find user with email example@company.com"

• "Show me details about customer Y"

• "Get recent conversations for account Z"

• "What tasks are open for account A?"

• "Add a note to account B about our recent call"

• "What tools can I use for account management?"

Troubleshooting

• If you encounter JSON parsing errors, ensure you've removed all console.log statements from the code

• Make sure your .env file contains the correct API credentials

• Check that you've built the project (npm run build) after making changes

• Verify the path in claude_desktop_config.json is absolute and correct for your system

• If you don't have a valid API key, the server will run in demo mode with mock data