Content
# Bittlebits MCP Server
A [Model Context Protocol](https://modelcontextprotocol.io) server that brings your [Bittlebits](https://bittlebits.ai) GEO scores and rewrite suggestions directly into AI agents — Claude Code, Cursor, VS Code, Codex, or any MCP-compatible client.
Instead of copying content back and forth, your agent can pull what Bittlebits recommends and apply those changes directly in your codebase.
---
## Quick start
```bash
npx @bittlebits.ai/mcp setup
```
This walks you through everything:
1. **Pick your clients** — Claude Code, Cursor, VS Code, Codex (any combination).
2. **Sign in** — a browser window opens; log into Bittlebits and you're done. Your API key is fetched and cached locally at `~/.bittlebits/config.json`.
3. **Connected** — the server is written into each client's config. Restart the client and start asking.
No copy-pasting keys, no hand-editing JSON.
> Already have an API key? Skip the browser:
> `npx @bittlebits.ai/mcp setup --api-key bb_your_key`
---
## What you can do
Once connected, ask your agent things like:
- *"Show me what Bittlebits wants to change on this page and explain why."*
- *"Rewrite my homepage copy applying the Bittlebits suggestions."*
- *"Which metrics are weakest and what should I fix first?"*
- *"Get the score for my landing page, then find and update the file in my codebase."*
---
## Available tools
| Tool | What it does |
|------|-------------|
| `get_score` | Returns GEO metric scores (0–10 per dimension) for a page |
| `get_rewrite` | Returns original and rewritten page content with Bittlebits suggestions applied |
| `get_url_content` | Returns the raw HTML and markdown of a page as fetched by Bittlebits |
All tools accept either a `url` (full page URL) or a `url_id` (Bittlebits internal ID if already known). Results may take a few minutes on first run while Bittlebits processes the page.
---
## The `setup` command
```
npx @bittlebits.ai/mcp setup [options]
--claude --cursor --vscode --codex Configure specific clients (skips the menu)
-p, --project Write project-scoped config (current directory)
--global Write user-global config
--api-key <key> Use this key instead of signing in
-y, --yes Non-interactive (use flags/defaults)
```
Where each client's config is written:
| Client | Project scope | Global scope |
|--------|---------------|--------------|
| Claude Code | `.mcp.json` | `~/.claude.json` |
| Cursor | `.cursor/mcp.json` | `~/.cursor/mcp.json` |
| VS Code | `.vscode/mcp.json` | user `mcp.json` |
| Codex | `.codex/config.toml` | `~/.codex/config.toml` |
Re-running `setup` is safe: it merges into existing files, preserving your other MCP servers, and only updates the Bittlebits entry.
---
## The `launch` command
Already ran `setup`? Use `launch` to instantly open an AI session with Bittlebits pre-loaded — no manual config needed.
```bash
npx @bittlebits.ai/mcp launch
```
This detects which AI clients (Claude Code, Codex) are installed on your machine and opens a session. If both are found, you'll be asked to pick one.
```
npx @bittlebits.ai/mcp launch [options]
-c, --client <name> Force a specific client: claude, codex
-p, --prompt <text> Send an initial prompt (non-interactive / scripted use)
```
**Examples:**
```bash
# Interactive session with auto-detected client
npx @bittlebits.ai/mcp launch
# Force Claude Code
npx @bittlebits.ai/mcp launch --client claude
# One-shot score in your terminal
npx @bittlebits.ai/mcp launch --client claude --prompt "Get the GEO score for nike.com"
```
---
## Manual configuration
Prefer to wire it up yourself? Any client that supports the stdio transport works. Run `npx bittlebits-mcp` with `BITTLEBITS_API_KEY` set in the environment — find your key under **Settings → API Keys** at [bittlebits.ai](https://bittlebits.ai).
**Claude Code (CLI):**
```bash
claude mcp add --transport stdio bittlebits -e BITTLEBITS_API_KEY=your_key -- npx -y @bittlebits.ai/mcp
```
**Cursor / Claude Code (`.cursor/mcp.json` or `.mcp.json`):**
```json
{
"mcpServers": {
"bittlebits": {
"command": "npx",
"args": ["-y", "@bittlebits.ai/mcp"],
"env": { "BITTLEBITS_API_KEY": "your_key_here" }
}
}
}
```
**VS Code (`.vscode/mcp.json`):**
```json
{
"servers": {
"bittlebits": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@bittlebits.ai/mcp"],
"env": { "BITTLEBITS_API_KEY": "your_key_here" }
}
}
}
```
**Codex (`~/.codex/config.toml`):**
```toml
[mcp_servers.bittlebits]
command = "npx"
args = ["-y", "@bittlebits.ai/mcp"]
[mcp_servers.bittlebits.env]
BITTLEBITS_API_KEY = "your_key_here"
```
---
## Prerequisites
- Node.js 18+
- A [Bittlebits](https://bittlebits.ai) account
---
## Development
```bash
git clone https://github.com/bittlebitsai/bittlebits-mcp
cd bittlebits-mcp # local dev still uses the folder name
npm install
npm run dev # run the server with tsx (no build step)
npm run build # compile to dist/
# Try the setup flow
node dist/index.js setup
```
Environment variables:
- `BITTLEBITS_API_KEY` — API key for server mode (skips browser login).
---
## Tips
- **Be specific about what to keep.** If brand voice matters, tell your agent: *"Apply the suggestions but keep the casual, conversational tone."*
- **Work section by section** on longer pages — easier to review.
- **Re-score after edits.** Once you've updated your page, trigger a new Bittlebits score to see how much the metrics improved.
