# mite MCP Server

Model Context Protocol server for the mite time tracking API.

[**mite**](https://mite.de/) – Simple time tracking for teams

## Prerequisites

- Node.js 18+
- mite account with API access enabled
- mite API key (recommended) or email/password

## Installation

```bash
npm install -g @marceloemmerich/mite-mcp
```

Or use directly with npx:

```bash
npx @marceloemmerich/mite-mcp
```

## Configuration

### For Development

1. Copy `.env.example` to `.env`:
   ```bash
   cp .env.example .env
   ```

2. Edit `.env` and fill in your credentials:
   ```bash
   MITE_ACCOUNT_NAME=your-account-name
   MITE_API_KEY=your-api-key
   ```

### For Production

Set the following environment variables:

```bash
# Required
MITE_ACCOUNT_NAME=your-account-name

# Authentication (use one of these)
MITE_API_KEY=your-api-key  # Recommended

# OR
MITE_EMAIL=your-email@example.com
MITE_PASSWORD=your-password
```

### Getting your mite API Key

1. Log into your mite account
2. Go to Settings > My User
3. Under "API Key", click "Display API Key"
4. Copy the key and set it as `MITE_API_KEY`

## Available Tools

### Time Entries

- `list_time_entries` - List time entries with optional filters
- `get_daily_time_entries` - Get time entries for today or a specific date
- `get_time_entry` - Get a specific time entry by ID
- `create_time_entry` - Create a new time entry
- `update_time_entry` - Update an existing time entry
- `delete_time_entry` - Delete a time entry

### Stopwatch

- `get_stopwatch_status` - Get current stopwatch status
- `start_stopwatch` - Start tracking time for an entry
- `stop_stopwatch` - Stop the currently running stopwatch
- `quick_start_stopwatch` - Create and start tracking a new entry

### Customers

- `list_customers` - List active or archived customers
- `get_customer` - Get a specific customer
- `create_customer` - Create a new customer (admin only)
- `update_customer` - Update a customer (admin only)
- `delete_customer` - Delete a customer (admin only)

### Projects

- `list_projects` - List active or archived projects
- `get_project` - Get a specific project
- `create_project` - Create a new project (admin only)
- `update_project` - Update a project (admin only)
- `delete_project` - Delete a project (admin only)

### Services

- `list_services` - List active or archived services
- `get_service` - Get a specific service
- `create_service` - Create a new service (admin only)
- `update_service` - Update a service (admin only)
- `delete_service` - Delete a service (admin only)

## Usage

### MCP Server Modes

The mite MCP server supports two modes:

#### 1. Stdio Mode (Default)
For use with Claude Desktop and other MCP clients that use stdio transport:

```bash
# Default stdio mode
npx @marceloemmerich/mite-mcp

# Explicitly specify stdio mode
npx @marceloemmerich/mite-mcp --stdio
```

#### 2. HTTP/Streamable Mode
For web-based clients or testing environments:

```bash
# HTTP/Streamable mode on default port 3000
npx @marceloemmerich/mite-mcp --http

# HTTP/Streamable mode on custom port and host
npx @marceloemmerich/mite-mcp --http --port 8080 --host 0.0.0.0
```

**HTTP Endpoints:**
- `POST /` - Handles MCP JSON-RPC requests
- `GET /` - Establishes SSE stream (requires Mcp-Session-Id header)
- `DELETE /` - Terminates session (requires Mcp-Session-Id header)


### CLI Options

```bash
mite-mcp [options]

Options:
  -V, --version      output the version number
  --stdio            Run in stdio mode (default)
  --http             Run in HTTP/Streamable mode
  -p, --port <port>  Port for HTTP server (default: 3000)
  -h, --host <host>  Host for HTTP server (default: localhost)
  --help             display help for command
```

### Claude Desktop Configuration

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "mite": {
      "command": "npx",
      "args": ["@marceloemmerich/mite-mcp"],
      "env": {
        "MITE_ACCOUNT_NAME": "your-account-name",
        "MITE_API_KEY": "your-api-key"
      }
    }
  }
}
```

For development testing with Claude Desktop, you can also use:

```json
{
  "mcpServers": {
    "mite-dev": {
      "command": "node",
      "args": ["dist/index.js"],
      "cwd": "/path/to/mite-mcp",
      "env": {
        "MITE_ACCOUNT_NAME": "your-account-name",
        "MITE_API_KEY": "your-api-key"
      }
    }
  }
}
```

You can also run directly from the CLI like this:
```bash
export MITE_ACCOUNT_NAME=<YOUR-ACCOUNT-NAME> && export MITE_API_KEY=<YOUR-API-KEY> && npx @marceloemmerich/mite-mcp --http --port 3000
```

## Development

```bash
# Clone the repository
git clone https://github.com/marceloemmerich/mite-mcp.git
cd mite-mcp

# Install dependencies
npm install

# Run in development mode (stdio)
npm run dev

# Run in HTTP/Streamable mode for testing
npm run dev -- --http --port 3000

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Build for production
npm run build

# Lint and format code
npm run lint:fix
```

### Testing HTTP/Streamable Mode

For testing the HTTP/Streamable server mode, you can use tools like:

```bash
# Test initialization (this will return a session ID)
curl -X POST http://localhost:3000/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{"roots":{"listChanged":true},"sampling":{}}},"id":1}'

# Test with session ID (replace SESSION_ID with the actual session ID from initialization)
curl -X GET http://localhost:3000/ \
  -H "Mcp-Session-Id: SESSION_ID"
```

### Development with Claude Desktop

For local development, update your Claude Desktop config:

```json
{
  "mcpServers": {
    "mite-dev": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/path/to/mite-mcp",
      "env": {
        "MITE_ACCOUNT_NAME": "your-account-name",
        "MITE_API_KEY": "your-api-key"
      }
    }
  }
}
```

## API Documentation

For detailed mite API documentation, visit: https://mite.de/api/

## License

MIT