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

1. Open the Kepler Developer Portal and sign in with GitHub.
2. Use Get Started or Register Client to create a service client. Pick a scope preset (e.g. Agent Builder) or choose scopes manually.
3. 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).
4. 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

• 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 configured gRPC host.
• KEPLER_GRPC_ENDPOINT is intended for advanced hosted-endpoint overrides, not local development.
• KEPLER_PORTAL_URL is not used by the npm package. Portal access is only for humans obtaining service credentials and downloading config fragments.