MCP Server

The Meridian Track MCP server lets AI assistants start and stop timers, log time entries, and manage projects and clients on your behalf. It uses the Model Context Protocol (MCP) — an open standard for connecting AI tools to external services.

Installation

The MCP server is included with the Meridian Track CLI. If you’ve already installed the CLI, you’re ready to go.

# macOS / Linux
curl -fsSL https://cli.meridiantrack.com/install.sh | bash

# Windows (PowerShell)
irm https://cli.meridiantrack.com/install.ps1 | iex

This provides the meridian-mcp command, which starts a stdio-based MCP server.

Authentication

Before configuring your AI assistant, set up credentials using one of these methods:

meridian auth login --api-key mt_live_your_key_here

The MCP server reads credentials from the same keyring and config file as the CLI.

Option 2: Environment Variables

Set MERIDIAN_API_KEY in the server configuration (see examples below). This is useful when keyring access is unavailable.

Setup

Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "meridian-track": {
      "command": "meridian-mcp",
      "env": {
        "MERIDIAN_API_KEY": "mt_live_your_key_here"
      }
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root (or ~/.cursor/mcp.json for global config):

{
  "mcpServers": {
    "meridian-track": {
      "command": "meridian-mcp",
      "env": {
        "MERIDIAN_API_KEY": "mt_live_your_key_here"
      }
    }
  }
}

Claude Code

Add to .mcp.json in your project root:

{
  "mcpServers": {
    "meridian-track": {
      "command": "meridian-mcp",
      "env": {
        "MERIDIAN_API_KEY": "mt_live_your_key_here"
      }
    }
  }
}

Or configure globally via claude mcp add:

claude mcp add meridian-track meridian-mcp

Other MCP Clients

Any MCP-compatible client can connect by running meridian-mcp as a stdio server. The server follows the MCP specification for tool discovery, invocation, and resource access.

Available Tools

The MCP server exposes 16 tools that AI assistants can call:

Timer

Tool	Description
`clock_in`	Start a timer with optional description, project, client, notes, billable flag, and tags
`clock_out`	Stop the running timer, optionally updating description, project, or notes
`get_timer_status`	Check if a timer is running and get elapsed time

Time Entries

Tool	Description
`create_time_entry`	Log a completed entry with start/end times, project, client, tags
`list_time_entries`	List entries by period (today, this_week, etc.) or custom date range
`update_time_entry`	Update description, project, client, notes, billable, end time, or tags
`delete_time_entry`	Delete a time entry by ID and sort key

Projects

Tool	Description
`list_projects`	List all projects with client associations
`create_project`	Create a project with optional client, billable default, color, hourly rate
`delete_project`	Delete a project by ID

Clients

Tool	Description
`list_clients`	List all clients with contact info and rates
`create_client`	Create a client with optional email, contact name, hourly rate
`delete_client`	Delete a client by ID

Tool	Description
`list_tags`	List all workspace tags
`create_tag`	Create a new tag
`delete_tag`	Delete a tag by ID

Available Resources

MCP resources provide passive context that AI assistants can read without invoking a tool:

Resource URI	Description
`meridian://today-summary`	Today’s total hours, entry count, billable count, and active timer
`meridian://projects`	All active projects with client associations
`meridian://clients`	All clients with IDs
`meridian://tags`	All workspace tags with IDs

Example Usage

Once configured, you can interact with Meridian Track naturally through your AI assistant:

You: Start a timer for the website redesign project

Assistant: Timer started at 9:15 AM on the “Website Redesign” project.

You: What did I work on today?

Assistant: Here are your entries for today:

Design review — 9:00 AM - 10:30 AM (1h 30m) [Website Redesign, billable]

Team standup — 10:30 AM - 11:00 AM (30m)

Total: 2h 0m (1 billable)

You: Log 2 hours for client meeting with Acme Corp yesterday from 2-4pm

Assistant: Time entry created: “Client meeting” from 2:00 PM - 4:00 PM (2h 0m), client: Acme Corp.

Troubleshooting

”Not authenticated” error

The server cannot find a valid API key. Verify with:

meridian auth status

If no key is shown, run meridian auth login or set MERIDIAN_API_KEY in your MCP server config.

Server not appearing in your AI assistant

Verify meridian-mcp is on your PATH:
Terminal window
```
which meridian-mcp
```
Restart your AI assistant after editing the configuration file.
Check that the JSON configuration is valid (no trailing commas, correct structure).

”No timer is currently running” when stopping

Only one timer can run at a time per user. Use get_timer_status (or meridian timer status in the CLI) to check state.