MCP Server

smartchats-mcp exposes the SmartChats data layer over the Model Context Protocol. Wire it into Claude Desktop (or any MCP-aware LLM client) and the LLM can read your logs, search your knowledge graph, browse metrics, run scoped queries, and import/export your data — all under your authentication.

It’s the same data path as the web app and the CLI: tools.ts is a thin wrapper that calls into operations.X(handle.data, args) or queries.X(args) and returns the result. There’s no separate MCP-only data plane; behavior matches the web app and CLI exactly.

Install + run

cd packages/smartchats-mcp
npm run build
node dist/index.js --target=cloud   # or --target=local

You typically don’t run this manually — your MCP client launches it over stdio.

Targets

The MCP server picks its data target at startup via --target:

• --target=cloud — your authenticated SmartChats cloud account.
• --target=local — your locally-running SmartChats instance.

For cloud, the server pre-authenticates before the protocol takes over (the browser-login flow needs interactive output). It uses the same credentials file as the CLI: ~/.smartchats-mcp/credentials.json — sign in once with smartchats login and both surfaces are authenticated.

# Cloud (default)
smartchats login                # one time
node dist/index.js --target=cloud
 
# Local
node dist/index.js --target=local

Local-mode connection details (URL, credentials, etc.) accept overrides via --local-* flags or matching SMARTCHATS_MCP_LOCAL_* env vars. Run smartchats-mcp --help to see them all.

Wire into Claude Desktop

cd packages/smartchats-mcp
npm run build

{
  "mcpServers": {
    "smartchats": {
      "command": "node",
      "args": [
        "/absolute/path/to/smartchats/packages/smartchats-mcp/dist/index.js",
        "--target=cloud"
      ]
    }
  }
}

Tools exposed

10 tools, organized by domain.

Read tools

run_query currently restricts to SELECT statements. Write capability — so MCP clients (and the CLI) can ingest data on your behalf as well as read it — is on the near roadmap.

Data movement tools

These delegate to the same operations.exportBundle / operations.importBundle the CLI uses. import_user_data accepts per-call URL/creds overrides for cross-environment imports — useful if you started the MCP in --target=cloud mode but want to import a bundle into your local AIO.

Example interactions

{
  "tool": "search_logs",
  "args": { "query": "morning routine", "limit": 10 }
}

[
  { "id": "logs:abc", "category": "wellness", "content": "Morning routine: ...", "ts": "2026-04-30T13:00:00Z", "local_date": "2026-04-30", "local_tz": "America/Chicago" },
  ...
]

{
  "tool": "query_knowledge_graph",
  "args": { "query": "project alpha", "limit": 20 }
}

{
  "tool": "run_query",
  "args": {
    "query": "SELECT category, count() AS n FROM logs GROUP BY category"
  }
}

Authentication notes

Cloud target: the MCP server authenticates as you. Every read and write is scoped to your account; the cloud surface enforces strict isolation between users.

Local target: your local SmartChats instance is yours alone — the MCP runs against it without an auth gate.

In both cases, your data stays your data. No cross-account leakage on the cloud side, no telemetry on the local side.

Architecture relationship

The MCP server is a consumer of the same shared infrastructure as the web app and the CLI:

        ┌─────────────────────────────────────────┐
        │         Operations + Query Builders     │   ← shared
        │       smartchats-database/{operations,  │
        │                            queries}/    │
        └─────────────────────────────────────────┘
            ▲                  ▲                ▲
            │                  │                │
       smartchats         smartchats         smartchats-mcp
         web app             CLI                ↑
                                          stdio JSON-RPC
                                                ↑
                                        Claude Desktop / etc.

When you add a new query builder in smartchats-database/src/queries/, the MCP can expose it as a tool with ~10 lines in tools.ts. There’s no duplicated logic between the CLI’s data subcommands and the MCP’s import_user_data / export_user_data tools — both call into operations.importBundle / operations.exportBundle.

See Architecture for the full picture.

Troubleshooting

See also

• CLI Reference — same operations, just for humans instead of LLMs.
• Architecture — the layered model that makes MCP a thin wrapper.
• Contributing — how to add a new MCP tool in 10 lines.