npm package: @kg-chat/mcp-server
Description: MCP server for KG Chat - Connect your notes and tables to any MCP client
Latest version: 1.0.3

# KG Chat MCP Server

Connect your KG Chat notes and tables to Claude Desktop and other MCP-compatible clients.

## What is MCP?

The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard that enables AI assistants like Claude to securely access your data and tools. This MCP server provides Claude with direct access to your KG Chat notes and tables.

## Features

- **Notes Management**: Create, read, update, and delete notes
- **Tables Management**: Manage table schemas and data
- **Secure Authentication**: Uses API tokens with granular permissions
- **Easy Setup**: Simple command-line interface

## Prerequisites

- Node.js 18 or higher
- A KG Chat account with API token (generate at `/settings/mcp`)
- Claude Desktop (for integration)

## Installation

No installation required! Use directly with npx:

```bash
npx @kg-chat/mcp-server --token YOUR_TOKEN
```

<!-- The CLI automatically reads `APP_URL` from your KG Chat app config (e.g., `.env.local`), so you only need to pass the API token. -->

## Getting Your API Token

1. Log in to your KG Chat account
2. Navigate to Settings → MCP Integration
3. Click "Create Token"
4. Select the permissions you need
5. Copy your token (it will only be shown once!)

## Configuration

### Environment Variables

- `APP_URL`: the base URL for your KG Chat deployment. The MCP server CLI automatically reuses this value.
- `KG_CHAT_API_TOKEN`: API token for authentication (lets you omit `--token`).

### Command-Line Options

```
Options:
  -t, --token <token>  API token for authentication (or set KG_CHAT_API_TOKEN)
  -a, --app-url <url>  KG Chat app URL (optional override, defaults to https://kgchat.app)
  -u, --url <url>      Legacy alias for `--app-url`
  -V, --version        output the version number
  -h, --help           display help for command
```

## Claude Desktop Integration

### macOS

1. Open the Claude Desktop config file:
   ```bash
   ~/Library/Application Support/Claude/claude_desktop_config.json
   ```

2. Add the following configuration:
   ```json
   {
     "mcpServers": {
       "kg-chat": {
         "command": "npx",
         "args": [
           "@kg-chat/mcp-server",
           "--token",
           "YOUR_TOKEN_HERE"
         ]
       }
     }
   }
   ```

The CLI automatically uses the `APP_URL` value that you configured for your KG Chat app, so you can keep the Claude Desktop config focused on the API token.

3. Restart Claude Desktop

### Windows

1. Open the Claude Desktop config file:
   ```
   %APPDATA%\Claude\claude_desktop_config.json
   ```

2. Add the same configuration as macOS

3. Restart Claude Desktop

### If you installed globally:

```json
{
  "mcpServers": {
    "kg-chat": {
      "command": "kg-chat-mcp",
      "args": [
        "--token",
        "YOUR_TOKEN_HERE"
      ],
    }
  }
}
```

Ensure your KG Chat app exports `APP_URL` (typically via `.env.local`) so the MCP server can connect without extra CLI flags.

## Available Tools

Once connected, Claude will have access to the following tools:

### Notes

- `list_notes` - List all your notes
- `get_note` - Get a specific note by ID
- `create_note` - Create a new note
- `update_note` - Update an existing note
- `delete_note` - Delete a note

### Tables

- `list_tables` - List all tables
- `get_table` - Get table schema and metadata
- `create_table` - Create a new table
- `update_table` - Update table schema
- `delete_table` - Delete a table
- `search_tables` - Search tables by name

### Table Rows

- `list_rows` - List all rows in a table
- `get_row` - Get a specific row
- `create_row` - Insert a new row
- `create_rows_batch` - Insert multiple rows at once
- `update_row` - Update an existing row
- `delete_row` - Delete a row

## Usage Examples

### In Claude Desktop

Once configured, you can ask Claude:

- "Can you list all my notes?"
- "Create a note titled 'Meeting Notes' with content about today's meeting"
- "Show me all tables"
- "Add a new row to the 'Customers' table with name 'John' and email 'john@example.com'"
- "Search for tables related to 'projects'"

## Permissions

The server requires API tokens with appropriate permissions:

- `notes:read` - Read notes
- `notes:write` - Create and update notes
- `notes:delete` - Delete notes
- `tables:read` - Read table schemas
- `tables:write` - Create and update tables
- `tables:delete` - Delete tables
- `table_rows:read` - Read table data
- `table_rows:write` - Insert and update rows
- `table_rows:delete` - Delete rows

## Troubleshooting

### "Error: API token is required"
Make sure you're passing the `--token` flag with your API token, or set `KG_CHAT_API_TOKEN` in your environment (e.g., `.env.local`).

### "Error: App URL not provided"
Set `APP_URL` in your `.env`/`.env.local`; the CLI automatically loads the value that your KG Chat app already uses.

### "Error: Invalid token format"
API tokens should start with `kg_live_`. Make sure you copied the full token.

### Authentication errors
Check that:
- Your token hasn't expired (check in Settings → MCP Integration)
- Your token has the required permissions
- Your KG Chat app exports the same `APP_URL` value that the MCP server relies on

### MCP server not showing up in Claude Desktop
- Make sure the config file is valid JSON
- Verify the path to the config file is correct
- Restart Claude Desktop after making changes
- Check the Claude Desktop logs for errors

## Security Best Practices

1. **Never commit tokens to version control**
2. **Use environment variables** for tokens in automated setups
3. **Set expiration dates** on tokens (30-90 days recommended)
4. **Use minimal permissions** - only grant what you need
5. **Rotate tokens regularly**
6. **Revoke unused tokens** immediately

## Development

### Building from source

```bash
# Clone the repository
git clone https://github.com/your-org/kg-chat-1.git
cd kg-chat-1/packages/mcp-server

# Install dependencies
npm install

# Build
npm run build

# Run locally
node dist/index.js --token YOUR_TOKEN
```

### Testing

To test the server without Claude Desktop:

```bash
# Run the server
npm run build
node dist/index.js --token YOUR_TOKEN

# The server communicates via stdin/stdout using the MCP protocol
# You can test with MCP debugging tools
```

## License

MIT

## Support

For issues and questions:
- Check the [documentation](https://your-docs-url.com)
- Open an issue on [GitHub](https://github.com/your-org/kg-chat-1/issues)

## Related Links

- [Model Context Protocol Documentation](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/desktop)
- [Convex Documentation](https://docs.convex.dev/)