@kepler-project/almanac

Kepler Almanac MCP Server

MCP server exposing Kepler Almanac tools (customers, communications, briefs, product gaps, Confluence/Jira search) for Claude Code, Cursor, OpenAI Codex CLI, and other stdio MCP clients.

Distribution:

• npm package @kepler-project/almanac: pure JavaScript MCP stdio server used directly via npx -y -p @kepler-project/almanac@latest -c almanac.
• No native binary is required for end users.

Portal onboarding and service credentials

• Open the Kepler Developer Portal and sign in with GitHub.
• Use Get Started or Register Client to create a service client. Pick a scope preset (e.g. Agent Builder) or choose scopes manually.
• Copy Client ID and Client Secret from the modal (the secret is only shown once). View client IDs later under My Clients (secrets cannot be retrieved again).
• Open the portal Kepler MCP tab to download Cursor, Claude Code, and Codex config fragments pre-filled with your values (all generation happens in the browser).

npm / npx

npx -y -p @kepler-project/almanac@latest -c almanac

The npx package runs as a JavaScript MCP server, connects to the hosted Kepler gRPC services, and mints its auth token internally from KEPLER_CLIENT_ID and KEPLER_CLIENT_SECRET.

Tool execution in this package is gRPC-only. The only HTTP request is the auth token mint to /v1/auth/service-token, which has no gRPC equivalent.

Requirements

The npm distribution targets hosted Kepler production services only. There is no local-dev mode in the npx package.

• KEPLER_CLIENT_ID (required): service client ID used to mint a Bearer token at /v1/auth/service-token.
• KEPLER_CLIENT_SECRET (required): service client secret paired with KEPLER_CLIENT_ID.
• KEPLER_GRPC_ENDPOINT (optional): advanced override for non-default gRPC targets. Most users should omit this.

MCP client configuration (summary)

Client	Where to merge
Cursor	~/.cursor/mcp.json (or project .cursor/mcp.json) under mcpServers
Claude Code	mcpServers in ~/.claude.json or project config per Anthropic docs
Codex CLI	~/.codex/config.toml – [mcp_servers.kepler-almanac] (see Codex MCP)

Use the portal Kepler MCP tab to download ready-made fragments.

Example shape (Cursor / Claude Code JSON):

{
  "mcpServers": {
    "kepler-almanac": {
      "command": "npx",
      "args": ["-y", "-p", "@kepler-project/almanac@latest", "-c", "almanac"],
      "env": {
        "KEPLER_CLIENT_ID": "your-client-id",
        "KEPLER_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Smoke validation (manual)

npx mode

• KEPLER_CLIENT_ID=... KEPLER_CLIENT_SECRET=... npx -y -p @kepler-project/almanac@latest -c almanac
• Missing KEPLER_CLIENT_ID or KEPLER_CLIENT_SECRET should fail fast.
• tools/list should advertise the Almanac, briefs, Salesforce, Confluence, Jira, and team tool families.

Operational notes

• In local-dev, record IDs use Surreal format (table:id); tool inputs accept id or communication_id where documented.
• In local-dev, schema uses dual-field compatibility for some fields (e.g. type / comm_type, occurred_at / started).
• In local-dev, vector/semantic search uses the graph store’s Surreal backend; ensure HNSW indices and schema are applied per Kepler infra.
• The published npm package is a pure JavaScript MCP stdio server.
• The package talks to hosted Kepler gRPC services and internally derives its auth base from the gRPC host.
• KEPLER_PORTAL_URL is not used by the npm package. Portal access is only for humans obtaining service credentials and downloading config fragments.