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) 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:

npx @kg-chat/mcp-server --token YOUR_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:

   ~/Library/Application Support/Claude/claude_desktop_config.json

2. Add the following configuration:

   {
     "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:

{
  "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 '[email protected]'"
• "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

# 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:

# 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
• Open an issue on GitHub

Related Links

• Model Context Protocol Documentation
• Claude Desktop
• Convex Documentation