lsp-setup

LSP Setup for Claude Code

Set up Language Server Protocol (LSP) support in Claude Code for any programming language. Handles binary installation, plugin configuration, and building custom plugins for languages not yet in the official marketplace.

Workflow

Phase 1: Assess current state

1. Read ~/.claude/settings.json to check:

   • enabledPlugins — which LSP plugins are already enabled
   • env.ENABLE_LSP_TOOL — whether the LSP tool is activated

2. List installed plugins:

   claude plugin list
   

3. Check which LSP binaries are already on PATH:

   which pyright-langserver typescript-language-server clojure-lsp gopls rust-analyzer lua-language-server 2>/dev/null
   

4. Identify the target language from $ARGUMENTS. If none specified, ask the user.

Phase 2: Check if a plugin already exists

Search the official marketplace:

claude plugin search [language]-lsp

If a plugin exists, skip to Phase 4 (install and enable).

Phase 3: Install the language server binary

Each language server has a preferred installation method. Use the best tool for the platform:

Language	Binary	Install command (macOS)	Install command (Linux)
Python	pyright-langserver	uv tool install pyright (preferred) or npm i -g pyright	same
TypeScript/JS	typescript-language-server	npm i -g typescript-language-server typescript	same
Clojure	clojure-lsp	brew install clojure-lsp/brew/clojure-lsp-native	download from GitHub releases
Go	gopls	go install golang.org/x/tools/gopls@latest	same
Rust	rust-analyzer	brew install rust-analyzer or rustup component add rust-analyzer	same
Lua	lua-language-server	brew install lua-language-server	download from GitHub releases
C/C++	clangd	brew install llvm	apt install clangd
C#	OmniSharp	dotnet tool install -g csharp-ls	same
Java	jdtls	brew install jdtls	download from eclipse.org
PHP	phpactor	composer global require phpactor/phpactor	same
Kotlin	kotlin-language-server	brew install kotlin-language-server	download from GitHub releases
Swift	sourcekit-lsp	Included with Xcode	N/A

Important notes:

• For Python, prefer uv tool install pyright over npm i -g pyright — it installs in an isolated venv and symlinks to ~/.local/bin/, avoiding npm permission issues.
• Claude Code's sandbox may block npm/pip global installs. If sandbox is enabled, the user may need to run the install command themselves outside Claude Code, or temporarily adjust sandbox settings.
• Verify the binary is on PATH after installation: which <binary-name>

Phase 4: Install and enable the plugin

# Install the plugin
claude plugin install <language>-lsp

# If not in official marketplace, install from a custom marketplace or repo:
# claude plugin marketplace add https://github.com/<user>/<marketplace-repo>.git
# claude plugin install <language>-lsp

Then update ~/.claude/settings.json:

1. Ensure ENABLE_LSP_TOOL is set:

   {
     "env": {
       "ENABLE_LSP_TOOL": "1"
     }
   }
   

2. Enable the plugin:

   {
     "enabledPlugins": {
       "<language>-lsp@claude-plugins-official": true
     }
   }
   

Phase 5: Build a custom plugin (if needed)

If no official plugin exists for the target language, build one.

5a. Plugin structure

<language>-lsp-plugin/
├── .claude-plugin/
│   └── plugin.json
└── README.md

5b. plugin.json with lspServers config

The key is the lspServers field in plugin.json:

{
  "name": "<language>-lsp",
  "version": "1.0.0",
  "description": "<Language> language server for code intelligence in Claude Code",
  "author": {
    "name": "<author>"
  },
  "license": "MIT",
  "lspServers": {
    "<server-name>": {
      "command": "<binary-name>",
      "args": ["--stdio"],
      "extensionToLanguage": {
        ".<ext1>": "<language-id>",
        ".<ext2>": "<language-id>"
      },
      "startupTimeout": 120000
    }
  }
}

Reference — official plugins use these language IDs:

• Python: "python" (extensions: .py, .pyi)
• TypeScript: "typescript" / "typescriptreact" (extensions: .ts, .tsx)
• JavaScript: "javascript" / "javascriptreact" (extensions: .js, .jsx)
• Clojure: "clojure" / "clojurescript" (extensions: .clj, .cljs, .cljc, .edn)
• Go: "go" (extensions: .go)
• Rust: "rust" (extensions: .rs)
• Lua: "lua" (extensions: .lua)

Use the language identifiers from the LSP specification: https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocumentItem

5c. Add to local marketplace fork

To make the plugin installable via claude plugin install:

1. Fork anthropics/claude-plugins-official if not already done
2. Add the plugin directory under plugins/<language>-lsp/
3. Add an entry to .claude-plugin/marketplace.json:

{
  "name": "<language>-lsp",
  "description": "<Language> language server for code intelligence",
  "version": "1.0.0",
  "author": { "name": "<author>" },
  "source": "./plugins/<language>-lsp",
  "category": "development",
  "strict": false,
  "lspServers": {
    "<server-name>": {
      "command": "<binary>",
      "args": ["--stdio"],
      "extensionToLanguage": {
        ".<ext>": "<language-id>"
      }
    }
  }
}

4. Install from fork:

claude plugin marketplace add https://github.com/<user>/claude-plugins-official.git#<branch>
claude plugin install <language>-lsp

5d. Submit to official marketplace

Submit standalone plugin repo at:

• https://claude.ai/settings/plugins/submit
• https://platform.claude.com/plugins/submit

Note: PRs to anthropics/claude-plugins-official are NOT the right way to publish — use the submission form.

Phase 6: Verify

1. Restart Claude Code (required for LSP changes to take effect)
2. Test with a file of the target language:

   # In Claude Code, use the LSP tool:
   LSP goToDefinition <file>:<line>:<col>
   LSP hover <file>:<line>:<col>
   LSP findReferences <file>:<line>:<col>
   

Troubleshooting

• LSP tool not available: Ensure ENABLE_LSP_TOOL=1 is in settings.json under env
• Server not connecting: Check which <binary> — the binary must be on PATH in Claude Code's shell
• Sandbox blocking installs: Install the binary manually outside Claude Code, then configure the plugin
• Slow startup: Some LSP servers (especially JVM-based like clojure-lsp) need "startupTimeout": 120000 or higher
• Plugin not found: If using a fork marketplace, ensure the branch name matches: claude plugin marketplace add <url>#<branch>