{"id":50412319,"url":"https://github.com/cskwork/serena-mcp-quickstart","last_synced_at":"2026-05-31T04:04:54.555Z","repository":{"id":356056131,"uuid":"1230838276","full_name":"cskwork/serena-mcp-quickstart","owner":"cskwork","description":"One-shot installer + Claude Code skill for Serena MCP. Wires LSP-powered semantic code search/edit into any project in 30s. Default preset: Java · Vue · TypeScript · Python · HTML, with 20+ opt-in languages.","archived":false,"fork":false,"pushed_at":"2026-05-06T11:35:24.000Z","size":28,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-06T13:34:03.619Z","etag":null,"topics":["ai-coding","anthropic","claude","claude-code","developer-tools","language-server","lsp","mcp","semantic-search","serena"],"latest_commit_sha":null,"homepage":null,"language":"Shell","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/cskwork.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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-05-06T11:21:05.000Z","updated_at":"2026-05-06T11:35:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/cskwork/serena-mcp-quickstart","commit_stats":null,"previous_names":["cskwork/serena-mcp-quickstart"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/cskwork/serena-mcp-quickstart","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fserena-mcp-quickstart","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fserena-mcp-quickstart/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fserena-mcp-quickstart/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fserena-mcp-quickstart/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cskwork","download_url":"https://codeload.github.com/cskwork/serena-mcp-quickstart/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cskwork%2Fserena-mcp-quickstart/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33718496,"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-05-31T02:00:06.040Z","response_time":95,"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":["ai-coding","anthropic","claude","claude-code","developer-tools","language-server","lsp","mcp","semantic-search","serena"],"created_at":"2026-05-31T04:04:53.834Z","updated_at":"2026-05-31T04:04:54.550Z","avatar_url":"https://github.com/cskwork.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# serena-mcp-quickstart\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/hero.svg\" alt=\"serena-mcp-quickstart — uvx serena, batteries included\" width=\"100%\" /\u003e\n\u003c/p\u003e\n\n\u003e One-shot installer that wires [Serena](https://github.com/oraios/serena) — the LSP-powered semantic code MCP server — into any Claude Code project in **under 30 seconds**.\n\nDefault preset enables LSPs for **Java · Vue · TypeScript (covers JS/React/TSX) · Python · HTML**, with one-line opt-ins for Go, Rust, C#, Kotlin, C/C++, Ruby, PHP, Swift, SCSS/CSS, and 20+ more.\n\n---\n\n## Install\n\n### Option A — bash one-liner (fastest)\n\n**Claude Code** (default):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/cskwork/serena-mcp-quickstart/main/install.sh | bash\n```\n\n**Codex CLI** (also registers in `~/.codex/config.toml`):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/cskwork/serena-mcp-quickstart/main/install.sh | bash -s -- --codex\n```\n\n**Codex CLI only** (skip Claude Code paths entirely):\n\n```bash\ncurl -fsSL https://raw.githubusercontent.com/cskwork/serena-mcp-quickstart/main/install.sh | bash -s -- --codex-only\n```\n\nRun from your project root. The installer will:\n\n1. Install [`uv`](https://astral.sh/uv) if missing.\n2. Drop the Skill into `~/.claude/skills/serena-mcp-quickstart/` (skipped with `--codex-only`).\n3. Register the Serena MCP server via `claude mcp add` (always — never hand-edits JSON):\n   - default → `claude mcp add serena --scope project` (writes `\u003cproject\u003e/.mcp.json`)\n   - `--global` → `claude mcp add serena --scope user` (writes `~/.claude.json`, the file Claude Code 2.x actually reads for user-scope MCP)\n   - `--codex` → also runs `codex mcp add serena ...` to register in `~/.codex/config.toml`\n   - `--codex-only` → only the Codex registration\n4. Generate `.serena/project.yml` pre-filled with the 5-language preset.\n5. Append a `## Tooling` section to your project's `CLAUDE.md` and/or `AGENTS.md` so future agents prefer Serena over grep. With `--codex` / `--codex-only`, also appends to your global `~/.codex/AGENTS.md`.\n6. **Auto-allow the 32 `mcp__serena__*` tools in `~/.claude/settings.json`** so Claude Code never prompts you for permission on first call. Skipped with `--codex-only` or `--no-permissions`.\n\nIdempotent — safe to re-run. Existing configs are merged, never overwritten. Existing Tooling blocks are detected via `\u003c!-- BEGIN serena-mcp-quickstart --\u003e` markers and skipped. Permissions allowlist entries are deduplicated.\n\n### Option B — copy-paste prompt (zero CLI required)\n\nPaste the block below into your CLI of choice (Claude Code, Codex, Gemini CLI). The agent figures out which host it's running on and registers Serena in the right place.\n\n```\nInstall Serena MCP for this project using https://github.com/cskwork/serena-mcp-quickstart.\n\nSteps:\n1. Verify uvx is installed; if not, install uv via the official script.\n2. Register the Serena MCP server. Detect which host you are running on and use the matching command:\n   - Claude Code (project scope, recommended):  cd \u003cproject\u003e \u0026\u0026 claude mcp add serena --scope project -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server\n   - Claude Code (user scope, all projects):     claude mcp add serena --scope user    -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server\n     IMPORTANT: do NOT hand-write ~/.claude/mcp.json — Claude Code 2.x ignores that path. The CLI writes to \u003cproject\u003e/.mcp.json or ~/.claude.json depending on scope.\n   - Codex CLI:  codex mcp add serena -- uvx --from git+https://github.com/oraios/serena serena start-mcp-server\n   - Gemini CLI: append the equivalent block to its MCP config (refer to Gemini CLI docs).\n3. Detect source files in the project. Map extensions to Serena enum values:\n   .java→java  .vue→vue  .ts/.tsx/.js/.jsx→typescript  .py→python  .html→html\n   (.css/.scss→scss  .go→go  .rs→rust  .cs→csharp  .kt→kotlin  .cpp/.c→cpp  etc.)\n   NEVER use js/javascript/react/jsx/tsx/css as enum values — they are not valid.\n4. Write .serena/project.yml with project_name=\u003crepo dir name\u003e and languages=\u003cdetected list\u003e.\n5. Append this block to CLAUDE.md (Claude Code) and/or AGENTS.md (Codex/Gemini CLI) — append to whichever exists in the project; create the file matching the active host if neither does. Skip if a BEGIN serena-mcp-quickstart marker is already present:\n   \u003c!-- BEGIN serena-mcp-quickstart --\u003e\n   ## Tooling\n\n   - When `mcp__serena__*` tools are loaded, prefer them for code search and symbol-level edits over `Grep`/`Read`/`Edit`. Fall back silently if absent.\n   \u003c!-- END serena-mcp-quickstart --\u003e\n6. Tell me to restart the CLI, then verify:\n   - In Claude Code 2.x, MCP tools are exposed as deferred tools — first call ToolSearch with query='select:mcp__serena__check_onboarding_performed,mcp__serena__activate_project' to load their schemas.\n   - Call mcp__serena__activate_project with project=\u003cabsolute project path\u003e. (On the very first run, check_onboarding_performed alone returns \"No active project\" until activate_project has registered it.)\n   - Call mcp__serena__check_onboarding_performed to confirm the project is active.\n```\n\n\u003e Heads-up: the first time Serena activates a project, it rewrites `.serena/project.yml` to its canonical schema (full comments, all keys). This is normal — your `project_name`, `languages`, and `ignored_paths` are preserved.\n\n---\n\n## What you get\n\nAfter install, every Claude Code or Codex CLI session in this project gains:\n\n- `mcp__serena__find_symbol` — jump to a definition by name across services\n- `mcp__serena__find_referencing_symbols` — true LSP references, not grep\n- `mcp__serena__rename_symbol` — refactor across files safely\n- `mcp__serena__replace_symbol_body` / `insert_after_symbol` — symbol-level edits\n- `mcp__serena__get_symbols_overview` — file/class/function tree on demand\n- 30+ more — see [tools list](https://oraios.github.io/serena/01-about/035_tools.html)\n\nThese are **dramatically more accurate than grep + read** in any non-trivial codebase, especially monorepos.\n\n---\n\n## Supported languages\n\n| Group | Enum values |\n|-------|-------------|\n| Default preset | `java`, `vue`, `typescript`, `python`, `html` |\n| Web (opt-in) | `scss` (CSS/SCSS/Sass), `angular` |\n| Backend (opt-in) | `go`, `rust`, `csharp`, `kotlin`, `cpp`, `ruby`, `php`, `swift`, `dart`, `scala`, `elixir`, `haskell`, `clojure`, `lua` |\n| Data / config | `yaml`, `json`, `markdown`, `bash`, `terraform` |\n| Niche | `lean4`, `solidity`, `nix`, `zig`, `crystal`, `julia`, `r`, `ocaml`, `erlang`, `fsharp`, `groovy` |\n\n**Aliases that are NOT valid enums** (Serena will crash on startup):\n- `js`, `javascript`, `react`, `jsx`, `tsx` → use `typescript`\n- `css` → use `scss`\n- `c` → use `cpp`\n\nCanonical list: [`solidlsp/ls_config.py`](https://github.com/oraios/serena/blob/main/src/solidlsp/ls_config.py)\n\n---\n\n## Why a Skill instead of a one-time script?\n\nThe bash installer covers the cold-start. The bundled `~/.claude/skills/serena-mcp-quickstart/SKILL.md` covers everything that comes after:\n\n- Adding a language to an existing project\n- Diagnosing \"language server not starting\" errors\n- Re-onboarding when you switch branches with different tooling\n- Setting up a new repo from scratch via natural-language prompt\n\nOnce installed, just say to Claude Code: *\"add Go to my Serena project.yml\"* or *\"why is my vue LSP failing\"* — the skill fires automatically.\n\nFor Codex CLI users, the skill file isn't auto-loaded by the host (Codex doesn't have a Skills mechanism), but the same SKILL.md serves as a copy-paste reference any time you need to extend `.serena/project.yml` or troubleshoot.\n\n---\n\n## Prerequisites\n\n| Tool | When required | Install |\n|------|---------------|---------|\n| `uv` / `uvx` | always | `curl -LsSf https://astral.sh/uv/install.sh \\| sh` |\n| Node 18+ | typescript, vue, html, angular, scss | nvm / brew / official |\n| JDK 17+ | java, kotlin, scala, groovy | `brew install openjdk@17` |\n| Python 3.10+ | python | system / pyenv |\n| Go 1.21+ | go | brew / official |\n| `rustup` | rust | https://rustup.rs |\n| .NET SDK 8+ | csharp | brew / official |\n\nYou only need toolchains for languages you actually enable.\n\n---\n\n## Troubleshooting\n\nSee [`skill/docs/troubleshooting.md`](skill/docs/troubleshooting.md). Top hits:\n\n- `uvx: command not found` — restart your shell after installing `uv`.\n- `KeyError: 'react'` in startup log — you have `react` (or `js`) in `languages:`. Replace with `typescript`.\n- Vue LSP hangs — run `npm install` in the repo root, then restart MCP.\n- Java LSP fails — `java -version` must show 17+; set `JAVA_HOME`.\n- Symbol search returns empty — first call triggers full index; wait 30–60s.\n\n---\n\n## How it compares\n\n| Approach | Setup time | Accuracy | Cross-language | Editing |\n|----------|------------|----------|----------------|---------|\n| `grep` + `read` | 0s | low (text match) | yes | no |\n| ctags / tree-sitter | minutes | medium | partial | no |\n| **Serena MCP (this skill)** | **~30s** | **high (LSP)** | **20+ languages** | **yes (symbol-level)** |\n\n---\n\n## Contributing\n\nPRs welcome. Especially valuable:\n\n- New language presets (`presets/\u003cstack\u003e.yml`) for common stacks: MERN, Spring + React, Django + Vue, etc.\n- Per-OS install hardening (Windows PowerShell variant, NixOS, etc.)\n- Translations of `SKILL.md` and `README.md`\n\nRun `bash -n install.sh` and `actionlint` locally before submitting.\n\n---\n\n## Credits\n\n- [Serena](https://github.com/oraios/serena) by Oraios — the actual MCP server doing all the heavy lifting.\n- This repo is a packaging convenience and is not affiliated with Oraios.\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcskwork%2Fserena-mcp-quickstart","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcskwork%2Fserena-mcp-quickstart","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcskwork%2Fserena-mcp-quickstart/lists"}