MCP server
Scribe's Model Context Protocol (MCP) server gives any compatible AI agent — Claude Code, Cursor, Codex, and more — a standard, secure way to read your work timeline and manage projects, clients, and invoices.
Two ways to connect
Hosted (hub)
Always-on, OAuth-secured, served from the cloud. Works on any machine with no desktop app running. Best for querying your synced timeline, projects, and invoices from anywhere.
Local (desktop app)
Served by the Scribe desktop app on localhost:3748. No sign-in needed. Available whenever the app is running (it runs in the background — the window does not need to be open).
Shows as not-connected when the desktop app isn't running.
Setup instructions
Pick your agent below. Each command registers Scribe as an MCP server. After adding it, restart your agent session so it picks up the new server.
Claude Code
The simplest path is the Scribe plugin, which bundles the local MCP server along with Scribe's skills:
/plugin marketplace add b-open-io/claude-plugins /plugin install scribe@b-open-io
Or register the MCP server directly. Local desktop app:
claude mcp add --transport http -s user scribe-desktop http://localhost:3748/api/mcp
Hosted hub (OAuth). If your client doesn't open the sign-in flow automatically on first use, trigger it with /mcp in Claude Code (or claude mcp login scribe):
claude mcp add --transport http -s user scribe https://getscribe.ai/api/mcp
Don't combine the plugin with a manual scribe-desktop entry — the plugin already includes it. If you added it by hand first, remove the duplicate with claude mcp remove scribe-desktop.
Codex CLI
codex mcp add scribe --url http://localhost:3748/api/mcp
codex mcp add scribe --url https://getscribe.ai/api/mcp
Cursor
Add to ~/.cursor/mcp.json (or a project .cursor/mcp.json):
{
"mcpServers": {
"scribe-desktop": {
"url": "http://localhost:3748/api/mcp"
}
}
}VS Code
Add to .vscode/mcp.json (VS Code uses a top-level servers key):
{
"servers": {
"scribe-desktop": {
"type": "http",
"url": "http://localhost:3748/api/mcp"
}
}
}Windsurf / Zed / older clients
For clients that don't speak streamable-HTTP natively, bridge through the mcp-remote proxy:
{
"mcpServers": {
"scribe-desktop": {
"command": "npx",
"args": ["-y", "mcp-remote", "http://localhost:3748/api/mcp"]
}
}
}Other clients
Any MCP client that supports a streamable-HTTP server works. Point it at http://localhost:3748/api/mcp (local) or https://getscribe.ai/api/mcp (hosted).
Tools available
Both surfaces expose the same core tools. The hosted server gates each tool by OAuth scope; the local server trusts the machine it runs on.
| Tool | Description | Scope |
|---|---|---|
| searchTimeline | Search timeline events (commits, AI chats, file changes) by keyword. | timeline:read |
| getRecentActivity | Summary of your activity over the last N days, grouped by source. | timeline:read |
| getProjectActivity | Activity summary for a single project over a time window. | timeline:read |
| listProjects | List your projects with their billable rates. | projects:read |
| listClients | List billing contacts / clients. | invoices:read |
| listInvoices | List invoices, optionally filtered by status. | invoices:read |
| createTimelineEntry | Manually log time to a project (1–480 minutes). | timeline:write |
Authentication
The hosted hub uses OAuth 2.1 with PKCE. On first connect, your agent opens a browser to sign in and authorize the scopes it needs; tokens refresh automatically after that. Headless tooling can pass a Scribe API key as a bearer token instead.
The local desktop server is bound to your machine and needs no sign-in. It only answers requests from localhost.
FAQ
The local server shows as failed / not connected.
That means the Scribe desktop app isn't running. The local MCP lives in the app's background process — start Scribe and it connects automatically. There's no window requirement; closing the window keeps the server running.
Do I need the desktop app for the hosted server?
No. The hosted hub serves your synced data from the cloud and works with no app installed. The desktop app adds machine-local capabilities (reading your git history and AI-assistant transcripts) that the cloud can't see.
Which one should I use?
Use the hosted hub for always-available access to your timeline, projects, and invoices. Add the local desktop server when you want agents to work with live, machine-local context. You can connect both.