@gleanwork/connector-mcp

An MCP server for AI-assisted Glean connector development. Add it to your IDE's MCP config and use Claude Code, Cursor, or any MCP-compatible AI assistant to scaffold, schema-map, generate, and test Glean connectors — without leaving your editor.

Prerequisites

• Node.js ≥ 20

• Python + uv (for run_connector and Copier scaffolding)

• A Glean API token

Setup

Claude Code

Add to .claude/mcp.json in your project (or ~/.claude/mcp.json globally):

{
  "mcpServers": {
    "local": {
      "command": "npx",
      "args": [
        "-y",
        "@gleanwork/connector-mcp"
      ],
      "type": "stdio"
    }
  }
}

For setup instructions for Cursor, VS Code, Windsurf, Goose, Codex, JetBrains, Gemini CLI, OpenCode, and more, see docs/setup.md.

Environment Variables

These are set in the MCP server config, not in your connector project.

GLEAN_INSTANCE and GLEAN_API_TOKEN belong in your connector project's .env file — create_connector generates a .env.example to get you started.

Quick Start

In your AI assistant, try:

"I want to build a Glean connector for our Salesforce Opportunities data. The API uses OAuth2 bearer tokens and returns paginated JSON. Let's start."

Or call get_started — the assistant will ask what you're connecting and walk you through the rest.

Core Workflow

Six steps from zero to a running connector. The assistant guides you through each one.

Tool Reference

Project Setup

Schema

Field Mapping

Data Client

Build & Run

Project Layout

After create_connector, your project directory looks like:

my-connector/
├── src/
│   └── {module_name}/
│       ├── connector.py    ← generated by build_connector
│       ├── models.py       ← generated TypedDict for source data
│       └── mock_data.json  ← sample data for local testing
├── CLAUDE.md           ← workflow guidance (for Claude Code users)
└── .glean/
    ├── schema.json     ← field schema
    ├── mappings.json   ← field mappings to Glean entity model
    ├── config.json     ← connector configuration
    ├── executions/     ← execution results (written on completion)
    └── recordings/     ← captured API responses for replay

MCP Resource

The server exposes a connector://workflow resource that returns the full authoring guide. Your AI assistant can fetch it at session start for workflow context.

Known Limitations

• Single project per MCP session. The server tracks one active project at a time. To switch projects, set GLEAN_PROJECT_PATH in the MCP server config or restart the server after running create_connector for the new project.

• Execution state is in-memory. Active execution history is lost when the MCP server restarts. Completed execution results written to .glean/executions/ persist on disk, but any in-progress executions must be re-run.

Troubleshooting

spawn uv ENOENT

uv is not installed or is not on your PATH. The server requires uv to scaffold connector projects and to run the Python worker.

Install it following the official uv instructions, then verify:

uv --version

If uv is installed but not on the PATH seen by your IDE, add it explicitly in the MCP server env config or set GLEAN_WORKER_COMMAND to the full path of an alternative command.

Copier template not found

The server could not locate the copier-glean-connector template. By default it looks for the template alongside this package in the Glean workspace or clones it from github.com/gleanwork over SSH.

Set the GLEAN_CONNECTOR_TEMPLATE_PATH environment variable to the absolute path of a local checkout of the template:

{
  "env": {
    "GLEAN_CONNECTOR_TEMPLATE_PATH": "/path/to/copier-glean-connector"
  }
}

Worker exited / glean.indexing.worker module not found

The Python worker process exited immediately. This usually means one of:

1. You are not inside a Copier-scaffolded connector project. The run_connector tool must be called after create_connector has set up the project directory with the correct pyproject.toml and dependencies.

2. The glean-indexing-sdk is not installed in the project's virtual environment. Run uv sync inside the connector project directory to install dependencies.

3. Wrong working directory. Ensure GLEAN_PROJECT_PATH points to the connector project root, or run create_connector first to set the active session path automatically.