Kodebase MCP Server

MCP server for Kodebase — query workspace state and create pull requests directly from Claude Code.

Setup

1. Generate an API Token

Go to Kodebase → Settings → API Tokens and create a new token. Copy it — it's only shown once.

2. Configure Claude Code

Run this in your terminal:

claude mcp add kodebase -s user \
  -e KODEBASE_API_TOKEN=kb_your_token_here \
  -e KODEBASE_URL=https://api.kodebase.studio \
  -- npx -y @kodelint/kodebase-mcp

That's it — restart Claude Code and the Kodebase tools will be available.

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "kodebase": {
      "command": "npx",
      "args": ["-y", "@kodelint/kodebase-mcp"],
      "env": {
        "KODEBASE_API_TOKEN": "kb_your_token_here",
        "KODEBASE_URL": "https://api.kodebase.studio"
      }
    }
  }
}

Remote / HTTP transport (Replit & other hosted agents)

Cloud agents like Replit can't spawn a local stdio process — they only connect to a remote MCP server over an HTTPS URL. The same package runs an HTTP transport for that:

MCP_TRANSPORT=http PORT=8080 KODEBASE_URL=https://api.kodebase.studio npx -y @kodelint/kodebase-mcp

• Stateless streamable-HTTP on POST /mcp, plus GET /health.
• No token env var in HTTP mode — each request authenticates with the caller's own token, sent as Authorization: Bearer <kb_…> or X-API-Key: <kb_…>. So every user acts as themselves.
• Host it behind HTTPS (e.g. https://mcp.kodebase.studio/mcp) — a reverse proxy terminating TLS in front of the PORT above.

Connect from Replit

1. In Replit: Settings → MCP Servers → + Add MCP server.
2. Display name: Kodebase.
3. Server URL: your HTTPS endpoint, e.g. https://mcp.kodebase.studio/mcp.
4. Advanced → custom header: X-API-Key = your kb_… token (from Kodebase → Settings → API Tokens).
5. Test & save.

Available Tools

ask

Ask Kodebase anything in natural language — todos, board state, task details, project info, pull requests, feedback. Returns a human-readable text response plus structured tasks when relevant.

create_pull_request

Open a PR on a Kodebase-connected GitHub repo. This is the only supported way to create a PR for a connected repo — agents should not fall back to gh pr create.

Inputs: owner, repo, title, head, base, optional body, draft, taskKey.

If taskKey (e.g. TES-001) is provided, the server appends (TES-001) to the title (when not already present) and links the PR to the matching task on the Kanban board, so the PR Summary feature picks it up automatically.

Development

npm install
npm run dev    # Run with tsx (hot reload)
npm run build  # Compile TypeScript

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | KODEBASE_API_TOKEN | stdio only | — | Your Kodebase API token (kb_...). Not used in http mode (token comes per-request from the header). | | KODEBASE_URL | No | https://api.kodebase.studio | Kodebase backend URL | | MCP_TRANSPORT | No | stdio | stdio for local clients (Claude Code); http for hosted clients (Replit). | | PORT | No | 8080 | Port for http transport. |