{"id":51094815,"url":"https://github.com/gleanwork/connector-mcp","last_synced_at":"2026-06-24T05:30:56.221Z","repository":{"id":343145805,"uuid":"1166898290","full_name":"gleanwork/connector-mcp","owner":"gleanwork","description":"MCP server that lets AI assistants (Claude Code, Cursor) scaffold,   schema-map, generate, and test Glean connectors","archived":false,"fork":false,"pushed_at":"2026-03-09T23:36:00.000Z","size":670,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-25T22:16:49.731Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gleanwork.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-25T18:20:47.000Z","updated_at":"2026-03-09T23:36:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gleanwork/connector-mcp","commit_stats":null,"previous_names":["gleanwork/connector-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/gleanwork/connector-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gleanwork%2Fconnector-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gleanwork%2Fconnector-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gleanwork%2Fconnector-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gleanwork%2Fconnector-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gleanwork","download_url":"https://codeload.github.com/gleanwork/connector-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gleanwork%2Fconnector-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34719084,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-24T05:30:55.467Z","updated_at":"2026-06-24T05:30:56.213Z","avatar_url":"https://github.com/gleanwork.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @gleanwork/connector-mcp\n\n[![Experimental](https://img.shields.io/badge/-Experimental-D8FD49?style=flat-square\u0026logo=data:image/svg+xml;base64,PHN2ZyB2aWV3Qm94PSIwIDAgMzIgMzIiIGZpbGw9Im5vbmUiIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyI+CjxwYXRoIGQ9Ik0yNC4zMDA2IDIuOTU0MjdMMjAuNzY1NiAwLjE5OTk1MUwxNy45MDI4IDMuOTk1MjdDMTMuNTY1MyAxLjkzNDk1IDguMjMwMTkgMy4wODQzOSA1LjE5Mzk0IDcuMDA5ODNDMS42NTg4OCAxMS41NjQyIDIuNDgzIDE4LjExMzggNy4wMzczOCAyMS42NDg5QzguNzcyMzggMjIuOTkzNSAxMC43ODkzIDIzLjcwOTIgMTIuODI3OSAyMy44MTc3QzE2LjE0NjEgMjQuMDEyOCAxOS41MDc3IDIyLjYyNDggMjEuNjc2NSAxOS44MDU1QzI0LjczNDQgMTUuODggMjQuNTE3NSAxMC40MTQ4IDIxLjQ1OTYgNi43Mjc4OUwyNC4zMDA2IDIuOTU0MjdaTTE4LjExOTcgMTcuMDUxMkMxNi4xMDI4IDE5LjYzMiAxMi4zNzI1IDIwLjEwOTEgOS43NzAwMSAxOC4wOTIyQzcuMTg5MTkgMTYuMDc1MiA2LjcxMjA3IDEyLjMyMzMgOC43MjkwMSA5Ljc0MjQ2QzkuNzA0OTQgOC40ODQ1OCAxMS4xMTQ2IDcuNjgyMTQgMTIuNjc2MSA3LjQ4Njk2QzEzLjA0NDggNy40NDM1OCAxMy40MTM1IDcuNDIxOSAxMy43ODIyIDcuNDQzNThDMTQuOTc1IDcuNTA4NjUgMTYuMTI0NCA3Ljk0MjM5IDE3LjA3ODcgOC42Nzk3N0MxOS42NTk1IDEwLjcxODQgMjAuMTM2NiAxNC40NzAzIDE4LjExOTcgMTcuMDUxMloiIGZpbGw9IndoaXRlIi8+CjxwYXRoIGQ9Ik0yNC41MTc2IDIxLjY5MjJDMjMuOTMyIDIyLjQ1MTMgMjMuMjgxNCAyMy4xMjM2IDIyLjU2NTcgMjMuNzUyNUMyMS44NzE3IDI0LjMzODEgMjEuMTEyNyAyNC44ODAzIDIwLjMxMDIgMjUuMzM1N0MxOS41Mjk1IDI1Ljc2OTUgMTguNjgzNyAyNi4xMzgyIDE3LjgzNzggMjYuNDIwMUMxNi45OTIgMjYuNzAyIDE2LjEwMjggMjYuODk3MiAxNS4yMTM3IDI3LjAwNTdDMTQuMzI0NSAyNy4xMTQxIDEzLjQzNTMgMjcuMTU3NSAxMi41MjQ0IDI3LjA5MjRDMTEuNjEzNSAyNy4wMjczIDEwLjcyNDMgMjYuODc1NSA5Ljg1Njg0IDI2LjY1ODdMOS42NjE2NSAyNy4zNzQzTDguNzcyNDYgMzAuOTk2MkM5LjkwMDIxIDMxLjI5OTggMTEuMDQ5NyAzMS40NzMzIDEyLjIyMDggMzEuNTZDMTIuMjY0MiAzMS41NiAxMi4zMjkyIDMxLjU2IDEyLjM3MjYgMzEuNTZDMTMuNTAwMyAzMS42MjUxIDE0LjY0OTggMzEuNTgxNyAxNS43NTU4IDMxLjQ1MTZDMTYuOTI3IDMxLjI5OTggMTguMDk4MSAzMS4wMzk1IDE5LjIyNTggMzAuNjcwOEMyMC4zNTM2IDMwLjMwMjIgMjEuNDU5NyAyOS44MjUgMjIuNTAwNyAyOS4yMzk1QzIzLjU2MzQgMjguNjUzOSAyNC41NjEgMjcuOTM4MiAyNS40OTM1IDI3LjE1NzVDMjYuNDQ3OCAyNi4zNTUgMjcuMzE1MyAyNS40NDQyIDI4LjA3NDQgMjQuNDQ2NUMyOC4xODI4IDI0LjMxNjQgMjguMjY5NSAyNC4xNjQ2IDI4LjM3OCAyNC4wMTI4TDI0Ljc3NzkgMjEuMzQ1MkMyNC42Njk0IDIxLjQ1MzcgMjQuNjA0NCAyMS41ODM4IDI0LjUxNzYgMjEuNjkyMloiIGZpbGw9IndoaXRlIi8+Cjwvc3ZnPg==\u0026labelColor=343CED)](https://github.com/gleanwork/.github/blob/main/docs/repository-stability.md#experimental)\n[![npm version](https://img.shields.io/npm/v/@gleanwork/connector-mcp.svg)](https://www.npmjs.com/package/@gleanwork/connector-mcp)\n[![CI](https://github.com/gleanwork/connector-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/gleanwork/connector-mcp/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nAn 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.\n\n## Prerequisites\n\n- Node.js ≥ 20\n- Python + [uv](https://docs.astral.sh/uv/) (for `run_connector` and Copier scaffolding)\n- A Glean API token\n\n## Setup\n\n### Claude Code\n\nAdd to `.claude/mcp.json` in your project (or `~/.claude/mcp.json` globally):\n\n```json snippet=docs/snippets/claude-code.json\n{\n  \"mcpServers\": {\n    \"local\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@gleanwork/connector-mcp\"\n      ],\n      \"type\": \"stdio\"\n    }\n  }\n}\n```\n\nFor setup instructions for Cursor, VS Code, Windsurf, Goose, Codex, JetBrains, Gemini CLI, OpenCode, and more, see [docs/setup.md](docs/setup.md).\n\n## Environment Variables\n\nThese are set in the MCP server config, not in your connector project.\n\n| Variable                        | Required | Description                                                                            |\n| ------------------------------- | -------- | -------------------------------------------------------------------------------------- |\n| `GLEAN_PROJECT_PATH`            | No       | Default project directory; overridden by `create_connector`                            |\n| `GLEAN_CONNECTOR_TEMPLATE_PATH` | No       | Path to a custom Copier template (defaults to `copier-glean-connector` in workspace)   |\n| `GLEAN_WORKER_COMMAND`          | No       | Command to start the Python worker (default: `uv run python -m glean.indexing.worker`) |\n| `GLEAN_WORKER_REQUEST_TIMEOUT`  | No       | Max seconds to wait for a worker JSON-RPC response (default: 30)                       |\n| `GLEAN_WORKER_SHUTDOWN_TIMEOUT` | No       | Seconds to wait for graceful worker shutdown before SIGKILL (default: 5)               |\n\n`GLEAN_INSTANCE` and `GLEAN_API_TOKEN` belong in your connector project's `.env` file — `create_connector` generates a `.env.example` to get you started.\n\n## Quick Start\n\nIn your AI assistant, try:\n\n\u003e \"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.\"\n\nOr call `get_started` — the assistant will ask what you're connecting and walk you through the rest.\n\n## Core Workflow\n\nSix steps from zero to a running connector. The assistant guides you through each one.\n\n| Step | What you're doing                                        | Tool                                     |\n| ---- | -------------------------------------------------------- | ---------------------------------------- |\n| 0    | Verify prerequisites                                     | `check_prerequisites`                    |\n| 1    | Scaffold the project                                     | `create_connector`                       |\n| 2    | Configure the data source                                | `set_config`                             |\n| 3    | Define the schema (infer from a sample file or write it) | `infer_schema` + `update_schema`         |\n| 4    | Map fields and verify required Glean fields are covered  | `confirm_mappings` + `validate_mappings` |\n| 5    | Generate the Python connector code                       | `build_connector`                        |\n| 5a   | Implement real API calls in data_client.py               | `get_data_client` + `update_data_client` |\n| 6    | Run the connector and inspect results                    | `run_connector` + `inspect_execution`    |\n\n## Tool Reference\n\n### Project Setup\n\n| Tool                  | Description                                                                  |\n| --------------------- | ---------------------------------------------------------------------------- |\n| `get_started`         | Open the guided workflow; the assistant asks what you're connecting          |\n| `check_prerequisites` | Verify uv, python, mise, copier, and Glean credentials are all configured    |\n| `create_connector`    | Scaffold a new connector project and set the active session path             |\n| `list_connectors`     | List all connector classes found in the project with their DataClient status |\n| `set_config`          | Write connector config (auth, endpoint, pagination) to `.glean/config.json`  |\n| `get_config`          | Read `.glean/config.json`                                                    |\n\n### Schema\n\n| Tool            | Description                                                           |\n| --------------- | --------------------------------------------------------------------- |\n| `infer_schema`  | Parse a `.csv`, `.json`, or `.ndjson` file and return field analysis  |\n| `get_schema`    | Read current `.glean/schema.json`                                     |\n| `update_schema` | Write field definitions to `.glean/schema.json`                       |\n| `analyze_field` | Deep-dive on a single field: samples, type, Glean mapping suggestions |\n\n### Field Mapping\n\n| Tool                | Description                                            |\n| ------------------- | ------------------------------------------------------ |\n| `get_mappings`      | Show source schema and Glean entity model side-by-side |\n| `confirm_mappings`  | Save field mapping decisions to `.glean/mappings.json` |\n| `validate_mappings` | Check mappings for missing required Glean fields       |\n\n### Data Client\n\n| Tool                 | Description                                                                               |\n| -------------------- | ----------------------------------------------------------------------------------------- |\n| `get_data_client`    | Read `data_client.py` and connector config — use before asking AI to write real API calls |\n| `update_data_client` | Write a new `data_client.py` implementation (replaces the mock with real API calls)       |\n\n### Build \u0026 Run\n\n| Tool                | Description                                                                                     |\n| ------------------- | ----------------------------------------------------------------------------------------------- |\n| `build_connector`   | Generate `src/{module}/connector.py`, `models.py`, `mock_data.json` from schema+mappings+config |\n| `run_connector`     | Start async connector execution; returns `execution_id` immediately                             |\n| `inspect_execution` | Poll execution status; returns records, validation issues, logs                                 |\n| `manage_recording`  | Record/replay/list/delete connector data recordings                                             |\n\n## Project Layout\n\nAfter `create_connector`, your project directory looks like:\n\n```\nmy-connector/\n├── src/\n│   └── {module_name}/\n│       ├── connector.py    ← generated by build_connector\n│       ├── models.py       ← generated TypedDict for source data\n│       └── mock_data.json  ← sample data for local testing\n├── CLAUDE.md           ← workflow guidance (for Claude Code users)\n└── .glean/\n    ├── schema.json     ← field schema\n    ├── mappings.json   ← field mappings to Glean entity model\n    ├── config.json     ← connector configuration\n    ├── executions/     ← execution results (written on completion)\n    └── recordings/     ← captured API responses for replay\n```\n\n## MCP Resource\n\nThe server exposes a `connector://workflow` resource that returns the full authoring guide. Your AI assistant can fetch it at session start for workflow context.\n\n## Known Limitations\n\n- **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.\n- **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.\n\n## Troubleshooting\n\n### `spawn uv ENOENT`\n\n`uv` is not installed or is not on your `PATH`. The server requires `uv` to scaffold connector projects and to run the Python worker.\n\nInstall it following the [official uv instructions](https://docs.astral.sh/uv/getting-started/installation/), then verify:\n\n```sh\nuv --version\n```\n\nIf `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.\n\n### `Copier template not found`\n\nThe 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.\n\nSet the `GLEAN_CONNECTOR_TEMPLATE_PATH` environment variable to the absolute path of a local checkout of the template:\n\n```json\n{\n  \"env\": {\n    \"GLEAN_CONNECTOR_TEMPLATE_PATH\": \"/path/to/copier-glean-connector\"\n  }\n}\n```\n\n### `Worker exited` / `glean.indexing.worker` module not found\n\nThe Python worker process exited immediately. This usually means one of:\n\n1. **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.\n2. **The `glean-indexing-sdk` is not installed** in the project's virtual environment. Run `uv sync` inside the connector project directory to install dependencies.\n3. **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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgleanwork%2Fconnector-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgleanwork%2Fconnector-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgleanwork%2Fconnector-mcp/lists"}