vitally-mcp

<!-- Copyright (c) 2024 John Jung --> # 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 1. Install dependencies: ```node npm install ``` 2. Create a `.env` file in the root directory with the following: ```text # 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: ```node 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 > (new page) Vitally REST API 3. Toggle the switch to enable the integration 4. 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 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: ```json { "mcpServers": { "vitally": { "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. ### Running the MCP via Docker 1. Edit the config file to add the Vitally MCP server from the GitHub package repository: ```json { "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" } } } } ``` 2. 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](<https://github.com/johnjjung/vitally-mcp>). ## 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](<https://github.com/johnjjung/vitally-mcp>) if you find an issue or if you would like an improvement.