Skip to main content
Meridian ships a TypeScript MCP (Model Context Protocol) server that gives any compatible AI tool read access to your local session database. Once connected, you can ask your AI assistant things like “what did I work on today?”, “which Jira ticket did I spend the most time on?”, or “what app am I using right now?” — and get answers drawn directly from your real activity data. The MCP server opens ~/.meridian/meridian.db in read-only mode on each tool call, so the AI always sees up-to-date session data without any manual syncing.

​
How the MCP server is built

./install.sh builds the MCP server automatically into packages/meridian-mcp/dist/index.js. If you need to rebuild it manually — for example after updating the repository — run: 
cd packages/meridian-mcp && npm run build
The server uses sql.js (pure WebAssembly SQLite) so it works with any Node.js version without native module compilation.

​
Add Meridian to your AI tool

Open (or create) the Claude Desktop configuration file:
~/Library/Application Support/Claude/claude_desktop_config.json
Add the meridian entry inside mcpServers. Replace /path/to/meridian with the absolute path to your cloned repository:
{
  "mcpServers": {
    "meridian": {
      "command": "node",
      "args": ["/path/to/meridian/packages/meridian-mcp/dist/index.js"]
    }
  }
}
Save the file, then quit and relaunch Claude Desktop. The Meridian tools will appear automatically in the tool picker.
You can find your repo path by running pwd inside the meridian directory.

​
Override the database path

By default the MCP server reads ~/.meridian/meridian.db. To point it at a different database file, set the MERIDIAN_DB environment variable in your MCP client config: 
{
  "mcpServers": {
    "meridian": {
      "command": "node",
      "args": ["/path/to/meridian/packages/meridian-mcp/dist/index.js"],
      "env": {
        "MERIDIAN_DB": "/custom/path/to/meridian.db"
      }
    }
  }
}

​
What you can ask your AI tool

Once connected, the AI has access to the following tools. You don’t need to invoke them by name — just ask naturally and the AI will choose the right one.

get-sessions

“What apps did I use today?” / “How long was I in VS Code this morning?”

get-timeline

“Walk me through my day.” / “What was I doing at 3 PM?” / “How many breaks did I take?”

get-stats

“How productive was I today?” / “What app did I spend the most time in?”

get-active-session

“What am I doing right now?” / “What app is currently active?”

get-active-task

“What Jira ticket am I working on right now?” / “What should I log time against?”

get-task-sessions

“What did I do on KAN-108 today?” / “How long have I spent on this ticket?”

get-task-breakdown

“How much time per ticket today?” / “How was my time split across Jira tickets?”

get-recent-sessions

“What did I do in the last 2 hours?” / “What have I been working on since lunch?”

search-sessions

“When did I work on the Stripe integration?” / “Find sessions where I was in a meeting.”

get-apps

“Which apps do I use most overall?” / “When did I last use Slack?”

get-session-detail

Full OCR text and window content for a specific session by ID.

health-check

“Is the Meridian daemon running?” / last sync status and session count.
For the complete input schema and parameter reference for each tool, see MCP Tools Reference.

​
Troubleshooting

Check two things:
  1. The daemon is running. Run meridian status — all four services (screenpipe, daemon, jira-updater, ui) should show as running.
  2. The database exists. Run ls -lh ~/.meridian/meridian.db. If the file is missing, the daemon hasn’t written any sessions yet. Wait for the first 60-second poll cycle to complete.
If the path is correct and the daemon is running, confirm the args path in your MCP config points to the actual dist/index.js file with no typos.
The MCP server loads the database file fresh on every tool call, so data should never be more than 60 seconds old (one daemon poll cycle). If results seem stale, run meridian logs to confirm the daemon is actively writing new sessions.
The MCP server uses sql.js (pure WebAssembly) instead of native SQLite bindings, so it is compatible with any modern Node.js version. If you see unexpected errors, rebuild the server with cd packages/meridian-mcp && npm run build and ensure you’re on Node 18 or later.
Tools like get-task-sessions, get-task-breakdown, and get-active-task require the AI classifier to have linked sessions to tickets. Confirm that CLASSIFICATION_ENABLED=true in ~/.meridian/.env and that at least one Jira, GitHub, or Linear integration is configured. Check meridian doctor for the classifier status.