Vitally MCP Server

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

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 for running locally

Install dependencies:
```
npm install
```

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

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

Navigate to your Vitally account
Go to Settings (⚙️) > Integrations > (new page) Vitally REST API
Toggle the switch to enable the integration
Copy the API Key (Secret Token)

Usage

There are three ways to use this MCP server:

Using the MCP Inspector

Run the MCP Inspector to test and debug the server:

npm run inspector

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

Running the MCP locally

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

Edit the config file to add the Vitally MCP server:

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

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

Running the MCP via Docker

Edit the config file to add the Vitally MCP server from the GitHub package repository:

{
  "mcpServers": {
    "vitally": {
         "command": "docker",
         "args": [
             "run",
             "--rm",
             "-i",
             "-e",
             "VITALLY_API_SUBDOMAIN",
             "-e",
             "VITALLY_API_KEY",
             "-e",
             "VITALLY_DATA_CENTER",
             "ghcr.io/fiscaltec/vitally-mcp"
         ],
         "env": {
             "VITALLY_API_SUBDOMAIN": "VITALLY_API_SUBDOMAIN",
             "VITALLY_API_KEY": "VITALLY_API_KEY",
             "VITALLY_DATA_CENTER": "VITALLY_DATA_CENTER"
         }
     }
  }
}

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

Attibution

As mentioned previously and in other files, this MCP has been created with original code from John Jung and containerised by Dan Searle.

All rightts go to John Jung.

Notes

This has only been tested with Claude Desktop as of this moment however, is likely to woth with others but the configuration may not translate and is untested.
Please raise an issue in either this repository, or the original if you find an issue or if you would like an improvement.