KPI Tracker MCP Server

A Model Context Protocol (MCP) server that integrates with the KPI Tracker automation API, making it easily consumable by both Claude Desktop (stdio) and Claude Web (HTTP/SSE) and other MCP-compatible AI assistants.

Features

• Complete API Coverage: Access all KPI Tracker automation endpoints
• Secure Authentication: Uses API key authentication with proper company scoping
• Rich Tool Set: 12+ tools for metrics, users, departments, journal entries, analytics, and more
• Type Safety: Built with TypeScript for robust type checking
• Easy Integration: Simple configuration for claude.ai

Available Tools

Metrics Management

• get_metrics - List all metrics with optional filtering
• get_metric - Get detailed metric information with statistics
• submit_metric_response - Submit a single metric response
• submit_batch_metric_responses - Submit multiple responses in batch
• get_metric_responses - Retrieve metric responses with filtering

Organization Data

• get_users - List users with role and department filtering
• get_departments - List all company departments

Journal & Documentation

• get_journal_entries - Retrieve journal entries with filtering
• create_journal_entry - Create new journal entries

Analytics & Reporting

• get_executive_summaries - Retrieve executive summaries
• get_analytics - Get company-wide analytics and insights

Installation

Quick Start

Install the package globally:

npm install -g kpi-tracker-mcp-server

Or use with npx (no installation required):

npx kpi-tracker-mcp-server

Development Setup

1. Clone the repository:

git clone https://github.com/your-username/kpi-tracker-mcp-server.git
cd kpi-tracker-mcp-server

2. Install dependencies:

npm install

3. Configure environment:

# Create .env file with your settings
echo "KPI_API_KEY=your_api_key_from_kpi_tracker" > .env
echo "KPI_BASE_URL=http://localhost:8000" >> .env

4. Build and test:

npm run build
npm run dev  # For stdio mode
npm run dev:http  # For HTTP mode

Integration Options

Claude Desktop Integration

Option 1: Using NPX (Easiest)

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "kpi-tracker": {
      "command": "npx",
      "args": ["kpi-tracker-mcp-server"],
      "env": {
        "KPI_API_KEY": "your_api_key_here",
        "KPI_BASE_URL": "http://localhost:8000"
      }
    }
  }
}

Option 2: Global Installation

1. Install globally:

npm install -g kpi-tracker-mcp-server

2. Configure Claude:

{
  "mcpServers": {
    "kpi-tracker": {
      "command": "kpi-tracker-mcp-server",
      "env": {
        "KPI_API_KEY": "your_api_key_here",
        "KPI_BASE_URL": "http://localhost:8000"
      }
    }
  }
}

Claude Web Integration

1. Start the HTTP server:

npm run start:http
# or for development
npm run dev:http

2. Configure Claude Web with the SSE endpoint:

{
  "mcpServers": {
    "kpi-tracker": {
      "url": "http://localhost:3001/sse"
    }
  }
}

Production Deployment

Using Docker:

# Build and run with Docker Compose
docker-compose up -d

# Or build manually
docker build -t kpi-mcp-server .
docker run -p 3001:3001 \
  -e KPI_API_KEY="your_api_key" \
  -e KPI_BASE_URL="https://your-domain.com" \
  kpi-mcp-server

Direct Node.js:

npm run build
npm run start:http

## API Key Setup

1. Log into your KPI Tracker admin panel
2. Navigate to API Keys section
3. Create a new API key with appropriate permissions:
   - `metrics.read` - For reading metrics and responses
   - `responses.write` - For submitting metric responses
   - `journal.read` - For reading journal entries
   - `journal.write` - For creating journal entries
   - `analytics.read` - For accessing analytics data

## Usage Examples

Once integrated with Claude.ai, you can use natural language to interact with your KPI data:

- "Show me all metrics for the sales department"
- "Submit a metric response: metric 5, value '8', user 12"
- "Get analytics data for the last month"
- "Create a journal entry about our Q4 performance"
- "List all users in the engineering department"

## Development

### Scripts

- `npm run build` - Build TypeScript to JavaScript
- `npm run dev` - Run stdio server in development mode
- `npm run dev:http` - Run HTTP server in development mode
- `npm start` - Run the compiled stdio server
- `npm start:http` - Run the compiled HTTP server
- `npm run lint` - Run ESLint
- `npm run typecheck` - Run TypeScript type checking

### Architecture

- `src/index.ts` - Stdio MCP server implementation (Claude Desktop)
- `src/http-server.ts` - HTTP/SSE MCP server implementation (Claude Web)
- `src/api-client.ts` - KPI Tracker API client wrapper
- `src/tools.ts` - MCP tool definitions and handlers
- `src/types.ts` - TypeScript type definitions

## Security Considerations

- API keys are transmitted securely via HTTPS
- API key-based company scoping ensures data isolation
- All API requests include proper authentication headers
- Environment variables keep sensitive data out of code

## Troubleshooting

### Common Issues

1. **"API request failed: 401 Unauthorized"**
   - Check that your API key is correct
   - Verify the API key has required permissions
   - Ensure the API key is associated with the correct company

2. **"Cannot connect to API"**
   - Verify `KPI_BASE_URL` is correct
   - Check that the KPI Tracker server is running
   - Confirm network connectivity

3. **"Tool not found"**
   - Ensure the MCP server is properly configured in Claude
   - Check that the server process is running
   - Verify the build completed successfully
   - For HTTP server: Check `http://localhost:3001/health` and `http://localhost:3001/tools`

4. **"Connection failed" (HTTP server)**
   - Verify the HTTP server is running on the correct port
   - Check firewall settings allow connections to port 3001
   - Ensure the SSE endpoint URL is correct: `http://localhost:3001/sse`

## License

MIT