npm package: @kontexted/mcp-cli
Description: [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
Latest version: 0.1.1
Deprecated: Package no longer supported. Contact Support at https://www.npmjs.com/support for more info.

# Kontexted MCP CLI

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)

**MCP client and proxy for connecting AI assistants to Kontexted.**

The Kontexted MCP CLI bridges AI coding assistants (opencode, Claude Code, etc.) with your Kontexted instance. It handles authentication, profile management, and translates MCP requests to your Kontexted server's API.

---

## What is this?

The [Kontexted](https://github.com/kontexted/kontexted) server provides an MCP (Model Context Protocol) endpoint that allows AI assistants to query your notes. Since Kontexted is open source, you can host multiple instances for different teams or environments, and each instance contains multiple workspaces.

This CLI helps you manage these scenarios by:

- **OAuth 2.0 Authentication** - Handles full OAuth flow with PKCE code verifier
- **Profile Management** - Store and switch between multiple Kontexted instances and workspaces
- **Workspace Scoping** - Narrows the LLM's context to a single workspace per profile
- **MCP Proxy Server** - Translates MCP stdio requests to HTTP calls to Kontexted
- **Tool Filtering** - Injects workspace context and controls write access per-profile

---

## Installation

### Prerequisites

- Kontexted server running at your instance

### Using npx / bunx (Recommended)

The easiest way to run Kontexted MCP CLI without installing:

```bash
# Using bunx
bunx @kontexted/mcp-cli

# Using npx
npx @kontexted/mcp-cli
```

No installation required - just replace `kontexted-mcp` with `bunx @kontexted/mcp-cli` or `npx @kontexted/mcp-cli` in all examples below.

### Global Install (Optional)

If you prefer a shorter command, install globally:

```bash
bun install -g @kontexted/mcp-cli
```

Then run directly:

```bash
kontexted-mcp
```

---

## Usage

### 1. Login

Authenticate with your Kontexted instance and store a profile:

```bash
kontexted-mcp login --url <mcp-server-url> --workspace <workspace-slug>
```

**Required flags:**
- `--url`: MCP server URL (e.g., `http://localhost:3000/api/mcp` or `https://app.example.com/api/mcp`)
- `--workspace`: Workspace slug from your Kontexted instance

**Optional flags:**
- `--alias <name>`: Store profile under a custom name (defaults to workspace name)
- `--write`: Enable write operations (create folders/notes) for this profile

**Examples:**

```bash
# Login to local development instance
kontexted-mcp login --url http://localhost:3000/api/mcp --workspace my-project

# Login to production with alias
kontexted-mcp login --url https://app.mycompany.com/api/mcp --workspace my-project --alias prod

# Login with write access enabled
kontexted-mcp login --url http://localhost:3000/api/mcp --workspace my-project --write
```

**What happens during login:**

1. CLI starts a temporary local HTTP server on port 8788
2. Opens your browser to Kontexted's OAuth authorization page
3. You sign in with Keycloak and authorize the MCP client
4. Kontexted redirects to the callback URL with an authorization code
5. CLI exchanges the code for access and refresh tokens
6. Tokens and client information are stored in `~/.kontexted/mcp.json`

---

### 2. View Stored Profiles

Show all configured profiles:

```bash
kontexted-mcp show-config
```

Output example:

```json
{
  "profiles": {
    "my-project": {
      "serverUrl": "http://localhost:3000/api/mcp",
      "workspace": "my-project",
      "write": false,
      "oauth": {
        "tokens": { "...": "..." },
        "codeVerifier": "...",
        "clientInformation": { "...": "..." }
      }
    },
    "prod": {
      "serverUrl": "https://app.mycompany.com/api/mcp",
      "workspace": "my-project",
      "write": true,
      "oauth": { "...": "..." }
    }
  }
}
```

---

### 3. Start MCP Proxy Server

Run the MCP proxy server (default command when no subcommand is provided):

```bash
kontexted-mcp [--alias <name> | --workspace <slug>] [--write | --write-off]
```

**Required flags (one or the other):**
- `--alias <name>`: Use profile by alias
- `--workspace <slug>`: Find profile by workspace name

**Optional flags:**
- `--write`: Override profile to enable write operations
- `--write-off`: Override profile to disable write operations

**Examples:**

```bash
# Start with default read-only access
kontexted-mcp --alias prod

# Start with write access for this session only
kontexted-mcp --alias my-project --write

# Start using workspace name instead of alias
kontexted-mcp --workspace my-project
```

The CLI will:
1. Load the specified profile from `~/.kontexted/mcp.json`
2. Connect to Kontexted's MCP server using stored tokens
3. List available tools and register them with MCP stdio transport
4. Remove `workspaceSlug` from tool input schemas (injected automatically)
5. Filter out write tools unless `--write` is specified
6. Wait for MCP requests from your AI assistant

---

### 4. Logout

Remove one or all stored profiles:

```bash
# Remove specific profile by alias
kontexted-mcp logout --alias prod

# Remove specific profile by workspace
kontexted-mcp logout --workspace my-project

# Remove all profiles
kontexted-mcp logout
```

---

## Integrating with opencode

The Kontexted MCP CLI is designed to work as an MCP server that can be configured in opencode.

### Step 1: Add MCP Server to opencode.json

Edit your project's `opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "kontexted": {
      "type": "local",
      "enabled": true,
      "command": ["kontexted-mcp", "--alias", "prod"],
    }
  }
}
```

Replace `--alias` with your profile name or use `--workspace` instead.

### Step 2: Configure Write Access (Optional)

If you want opencode to create notes or folders in Kontexted:

1. Enable write access during login: `kontexted-mcp login --url <url> --workspace <slug> --write`
2. Or override per-session: `"args": ["--alias", "prod", "--write"]`

### Step 3: Restart opencode

Restart your opencode session to load the MCP server.

### Step 4: Use Kontexted Tools

opencode can now access Kontexted MCP tools:

- `getWorkspaceTree` - Fetch workspace structure (folders and notes)
- `searchNotesByQuery` - Search notes by name or title
- `getNoteById` - Retrieve a specific note's content
- `createFolder` - Create a new folder (requires `--write`)
- `createNote` - Create a new note (requires `--write`)

The CLI automatically injects your configured `workspaceSlug` into all requests, so you don't need to specify it manually.

---

## Tool Filtering

The CLI filters MCP tools based on your profile's write settings:

| Tool | Read-Only | With Write |
|-------|------------|------------|
| `getWorkspaceTree` | ✅ | ✅ |
| `searchNotesByQuery` | ✅ | ✅ |
| `getNoteById` | ✅ | ✅ |
| `createFolder` | ❌ | ✅ |
| `createNote` | ❌ | ✅ |

By default, profiles are created in read-only mode. Use `--write` during login or session start to enable write operations.

---

## Configuration File

Profiles are stored in:

```
~/.kontexted/mcp.json
```

Each profile contains:
- `serverUrl`: Kontexted MCP server URL
- `workspace`: Workspace slug
- `write`: Default write access setting
- `oauth.tokens`: OAuth access and refresh tokens
- `oauth.codeVerifier`: PKCE code verifier for token refresh
- `oauth.clientInformation`: OAuth client metadata

**Security Note:** Tokens are stored in plain text on disk. Ensure your system's `~/.kontexted` directory has appropriate permissions.

---

## Troubleshooting

### "Unauthorized. Run 'kontexted-mcp login' first."

Your tokens have expired or are missing. Run login again:

```bash
kontexted-mcp login --url <url> --workspace <workspace>
```

The CLI will automatically refresh expired tokens when possible.

### "Failed to open browser"

The CLI couldn't automatically open your browser. Copy the URL from your terminal and open it manually.

### Port 8788 already in use

The OAuth callback server requires port 8788. If it's occupied:

1. Close other processes using the port, or
2. Manually copy the authorization URL from the CLI output

### Profile not found

Check your stored profiles:

```bash
kontexted-mcp show-config
```

Use the exact alias or workspace name shown in the output.

---

## Development

For contributing or running from source code:

```bash
# Clone repository
git clone https://github.com/kontexted/kontexted-mcp-cli.git
cd kontexted-mcp-cli

# Install dependencies
bun install

# Run from source
bun run start

# Build distribution
bun run build
```

**Note:** Building from source is only necessary for development. For regular use, run with `bunx` or `npx` instead.

---

## License

[MIT License](LICENSE) - Copyright (c) 2026 Rabbyte

---

## Links

- [Kontexted Server](https://github.com/kontexted/kontexted) - Main Kontexted application
- [Issues & Bug Reports](https://github.com/kontexted/kontexted-mcp-cli/issues)
- [Model Context Protocol](https://modelcontextprotocol.io/) - MCP specification