Skip to main content
The Avala MCP server is distributed as an npm package and can be installed globally or used with npx.

​
Prerequisites

1

Node.js requirement

The MCP server requires Node.js 18 or higher. Check your version:
node --version
If you need to install or update Node.js, visit nodejs.org.
2

Avala API key

You’ll need an Avala API key to authenticate requests. Get your key from the Avala dashboard.
Keep your API key secure. Never commit it to version control or share it publicly.

​
Installation options

​
Option 1: Install globally

Install the MCP server as a global npm package: 
npm install -g @avala-ai/mcp-server
Verify the installation: 
avala-mcp-server --version

​
Option 2: Use with npx

Run the server directly without installing: 
npx @avala-ai/mcp-server
Using npx is recommended for testing and one-off usage. For production integrations, install globally for better performance.

​
Configure your AI assistant

The MCP server uses stdio (standard input/output) for communication. Configuration varies by client:
Add the Avala MCP server to your Claude Desktop configuration file.macOS: ~/Library/Application Support/Claude/claude_desktop_config.jsonWindows: %APPDATA%\Claude\claude_desktop_config.json
{
  "mcpServers": {
    "avala": {
      "command": "npx",
      "args": ["-y", "@avala-ai/mcp-server"],
      "env": {
        "AVALA_API_KEY": "your-api-key-here"
      }
    }
  }
}
Replace your-api-key-here with your actual Avala API key.
If you installed globally, use the direct command:
{
  "mcpServers": {
    "avala": {
      "command": "avala-mcp-server",
      "env": {
        "AVALA_API_KEY": "your-api-key-here"
      }
    }
  }
}
Restart Claude Desktop for changes to take effect.

​
Verify the connection

Once configured, test the connection by asking your AI assistant: 
List my Avala datasets
Show me my annotation projects
Get workspace statistics
If the MCP server is properly configured, your assistant will use the Avala tools to respond with data from your workspace.

​
Troubleshooting

Error: AVALA_API_KEY environment variable is requiredSolution: Verify that your API key is correctly set in the environment configuration. Check for:
  • Typos in the environment variable name
  • Missing or incorrect API key value
  • Extra whitespace around the key
Error: avala-mcp-server: command not foundSolution:
  • If using npx, ensure you have internet connectivity
  • If installed globally, verify npm’s global bin directory is in your PATH
  • Try reinstalling: npm install -g @avala-ai/mcp-server
Error: This package requires Node.js 18 or higherSolution: Update Node.js to version 18 or later:
# Using nvm (recommended)
nvm install 18
nvm use 18
Problem: AI assistant doesn’t show Avala toolsSolution:
  • Restart your AI assistant application
  • Check the configuration file syntax (valid JSON)
  • Review application logs for connection errors
  • Test the server manually by running the command in your terminal

​
Next steps

Configuration

Learn how to enable write operations and configure server options

Build docs developers (and LLMs) love

Get started for freeTalk to us