Byterover MCP Server

<div align="center">
  <h1>Byterover MCP Server</h1>
  <h3>Powering Coding Agent Collaboration with Shared Memory</h3>
</div>

<br/>

Give [Cursor](https://cursor.sh/), [Windsurf](https://codeium.com/windsurf), [Cline](https://cline.bot/), and other AI-powered coding agents the shared long term memory so that they can perform the task well together with the relevant context with this [Model Context Protocol](https://modelcontextprotocol.io/introduction) server.

When Cursor has the knowledge about the codebase; experiences in the past about how it has solved the project's issues with human it's **way** better and cost effective than re-entering the reasoning loop again.

<h3><a href="https://www.byterover.dev/docs/get-started">See quickstart instructions →</a></h3>

## How it works

1. Open your IDE's chat (e.g. agent mode in Cursor).
2. Let the Agent know how they're going to use the external memories (cursor rules, etc.)
3. Cursor will retrieve and store the relevant memories while performing the tasks

## Getting Started

Many code editors and other AI clients use a configuration file to manage MCP servers.

The `byterover-mcp` server can be configured by adding the following to your configuration file.

> NOTE: You can either provide your Byterover API key and user ID in the configuration or start the server without credentials and configure it later via the API endpoints. Instructions on how to create a Byterover API access token can be found [here](https://www.byterover.dev/docs/get-started).

### MacOS / Linux

```json
{
  "mcpServers": {
    "Byterover Memory MCP": {
        "command": "npx",
        "args": [
          "-y",
          "byterover-mcp",
          "--byterover-public-api-key=YOUR-PUBLIC-KEY",
          "--user-id=YOUR-NAME",
          "--llm-key-name=YOUR-LLM-KEY-NAME",
          "--model=YOUR-LLM-MODEL-NAME"
        ]
      }
  }
}
```

### Windows

```json
{
  "mcpServers": {
    "Byterover Memory MCP": {
      "command": "cmd",
      "args": [
          "/c",
          "npx",
          "-y",
          "byterover-mcp",
          "--byterover-public-api-key=YOUR-PUBLIC-KEY",
          "--user-id=YOUR-NAME",
          "--llm-key-name=YOUR-LLM-KEY-NAME",
          "--model=YOUR-LLM-MODEL-NAME"
      ]
    }
  }
}
```

If you need more information about Byterover see the [Byterover docs](https://www.byterover.dev).

## Running Without Initial Credentials

You can now start the Byterover MCP server without providing the API key and user ID upfront:

```bash
# Install the package
npm install -g byterover-mcp

# Start the server without credentials
byterover-mcp

# Start the server on a custom port
byterover-mcp --port 3334
```

The server will start with limited functionality and provide instructions on how to configure it. By default, the server runs on port 3333, but you can specify a custom port using the `--port` option as shown above.

### Configuring via API

Once the server is running, you can configure it using the following API endpoints:

#### Update Credentials

```bash
curl -X POST http://localhost:3333/config \
  -H "Content-Type: application/json" \
  -d '{"byteroverPublicApiKey":"YOUR_API_KEY","userId":"YOUR_USER_ID"}'
```

#### Check Configuration Status

```bash
curl http://localhost:3333/config/status
```

### Running with Node.js

If you're running the server directly with Node.js:

```bash
# Build the project
npm run build

# Start without credentials
node dist/cli.js

# Start on a custom port
node dist/cli.js --port 3334

# Or start with credentials
node dist/cli.js --byterover-public-api-key=YOUR_API_KEY --user-id=YOUR_USER_ID

# Start with credentials on a custom port
node dist/cli.js --byterover-public-api-key=YOUR_API_KEY --user-id=YOUR_USER_ID --port 3334

# You can also set the port using an environment variable
PORT=3334 node dist/cli.js
```

## Requirements

- Node.js version 20 or higher