TypeScript MCP Server

A lightweightModel Context Protocol(MCP) server forTypeScript and JavaScript refactoring and code intelligence. Every tool maps directly to atsserverprotocol command — the output is the raw, unmodified response from TypeScript's compiler. Rename symbols, extract functions, move declarations between files, reorganize imports, navigate type hierarchies, explore call graphs, search symbols across your workspace, map AI-generated code into the right locations, discover which error codes have automatic fixes, and more — with everyimport,require, re-export, and reference updated automatically across your entire codebase.

ts-mcp-servergives any MCP-compatible client —VS Code Copilot,Claude Desktop,Cursor,Windsurf,Continue, and others — the ability to perform these refactorscorrectly and completely, using TypeScript's own compiler infrastructure.

{ "servers": { "ts-mcp-server": { "command": "npx", "args": ["ts-mcp-server"] } } }

Claude Desktop(claude_desktop_config.json):

{ "mcpServers": { "ts-mcp-server": { "command": "npx", "args": ["ts-mcp-server"] } } }

Cursor, Windsurf, Continue— follow each client's MCP server documentation using the samenpx ts-mcp-servercommand.

Every tool can be disabled individually by setting its name to"false"in theenvblock of your MCP configuration. Tools are enabled by default; only tools explicitly set to"false"are skipped at startup.

{ "servers": { "ts-mcp-server": { "command": "npx", "args": ["ts-mcp-server"], "env": { "todoComments": "false", "getOutliningSpans": "false", "docCommentTemplate": "false" } } } }

Claude Desktop(claude_desktop_config.json):

{ "mcpServers": { "ts-mcp-server": { "command": "npx", "args": ["ts-mcp-server"], "env": { "todoComments": "false", "getOutliningSpans": "false", "docCommentTemplate": "false" } } } }

The tool name inenvmust exactly match the tool name as listed in theTool Referencebelow (e.g.,"quickinfo","getDiagnostics","extractFunction"). Any other value — including omitting the key entirely — leaves the tool enabled.

rename file="src/utils/helpers.ts" line=5 offset=17 newName="formatCurrency" rename file="src/components/Button.tsx" line=10 offset=17 newName="PrimaryButton" rename file="src/types.ts" line=3 offset=11 newName="UserProfile" rename file="src/utils/helpers.ts" line=5 offset=17 newName="formatCurrency" preview=true

renameFileOrDirectory from="src/utils/helpers.ts" to="src/utils/string-helpers.ts" renameFileOrDirectory from="src/Button.tsx" to="src/components/ui/Button.tsx" renameFileOrDirectory from="src/components/primitives" to="src/components/ui" renameFileOrDirectory from="src/old-name.ts" to="src/new-name.ts" preview=true

references file="src/utils/helpers.ts" line=5 offset=17 references file="src/types.ts" line=3 offset=11

getDiagnostics file="src/utils/helpers.ts" getDiagnostics file="src/components/Button.tsx"

organizeImports file="src/utils/helpers.ts" organizeImports file="src/components/Button.tsx" preview=true

# Get fixes for a "Cannot find name" error (code 2304) at line 10 getCodeFixes file="src/app.ts" startLine=10 startOffset=1 endLine=10 endOffset=20 errorCodes=[2304] # Get fixes for multiple error codes getCodeFixes file="src/app.ts" startLine=5 startOffset=1 endLine=5 endOffset=30 errorCodes=[2304, 2552]

Get a combined code fix that applies all instances of a fix across a file in one action. Returns the full set of file edits as aCombinedCodeActionsresponse. UsegetCodeFixesfirst to discover availablefixIdvalues, then pass thefixIdhere to get the combined fix for the whole file.

# Get the combined "add all missing imports" fix for a file getCombinedCodeFix file="src/app.ts" fixId="fixMissingImport" # Get the combined "remove all unused variables" fix for a file getCombinedCodeFix file="src/app.ts" fixId="unusedIdentifier"

Extract a selected code range into a new function. TypeScript auto-detects parameters and return type. The response includesrenameFilename/renameLocationso you can follow up withrenameto give the function a meaningful name.

# Extract lines 10-15 into a function extractFunction file="src/app.ts" startLine=10 startOffset=1 endLine=15 endOffset=1 # Preview the extraction extractFunction file="src/app.ts" startLine=10 startOffset=1 endLine=15 endOffset=1 preview=true

Extract a selected expression into a named constant. TypeScript infers the type. The response includesrenameFilename/renameLocationso you can follow up withrenameto give the constant a meaningful name.

# Extract an expression into a constant extractConstant file="src/app.ts" startLine=8 startOffset=12 endLine=8 endOffset=35 # Preview the extraction extractConstant file="src/app.ts" startLine=8 startOffset=12 endLine=8 endOffset=35 preview=true

Move top-level declarations (functions, classes, types, constants) to another file. All imports across the project are rewired automatically. If the target file doesn't exist, tsserver creates it.

# Move a function to a utility file moveSymbol file="src/app.ts" startLine=20 startOffset=1 endLine=35 endOffset=2 targetFile="src/utils/helpers.ts" # Move a type to a shared types file moveSymbol file="src/components/Button.tsx" startLine=1 startOffset=1 endLine=5 endOffset=2 targetFile="src/types.ts" # Preview the move moveSymbol file="src/app.ts" startLine=20 startOffset=1 endLine=35 endOffset=2 targetFile="src/utils/helpers.ts" preview=true

Inline a variable — replace all references with the variable's initializer and delete the declaration. Position must be on the variable name in its declaration or any usage.

# Inline a variable inlineVariable file="src/app.ts" line=12 offset=7 # Preview the inlining inlineVariable file="src/app.ts" line=12 offset=7 preview=true

Extract an inline type annotation into a named type alias. Select the type span to extract. The response includesrenameFilename/renameLocationso you can follow up withrenameto give the type a meaningful name.

# Extract an inline object type into a type alias # Given: function process(user: { id: number; name: string }) { ... } # Select the span "{ id: number; name: string }" extractType file="src/app.ts" startLine=5 startOffset=26 endLine=5 endOffset=56 # Preview the extraction extractType file="src/app.ts" startLine=5 startOffset=26 endLine=5 endOffset=56 preview=true

Add an explicit return type annotation to a function, inferred by TypeScript. Position must be on the function name or declaration keyword (function,async, arrow function variable name).

# Add return type to a function that currently has none # Given: function greet(name: string) { return Hello, ${name}!; } # After: function greet(name: string): string { return Hello, ${name}!; } inferReturnType file="src/app.ts" line=10 offset=10 # Preview the change inferReturnType file="src/app.ts" line=10 offset=10 preview=true

Get the full type information, documentation, and JSDoc tags for the symbol at a given position. This is the "hover" info.

quickinfo file="src/utils/helpers.ts" line=5 offset=17 quickinfo file="src/types.ts" line=3 offset=11

Get the complete hierarchical structure of a file — all classes, functions, variables, interfaces, type aliases, enums, and their nesting.

navtree file="src/utils/helpers.ts" navtree file="src/components/Button.tsx"

Go to the definition of a symbol. Returns the file location(s) where the symbol is declared.

definition file="src/app.ts" line=10 offset=5 definition file="src/components/Button.tsx" line=3 offset=15

Navigate to the type's definition, not the variable's declaration. Givenconst user: UserProfile = ...,definitiongoes to the variable, buttypeDefinitiongoes to theUserProfileinterface.

typeDefinition file="src/app.ts" line=10 offset=12 typeDefinition file="src/services/api.ts" line=5 offset=8

Find concrete implementations of an interface or abstract class. Given an interfaceSerializable, returns every class that implements it.

implementation file="src/types.ts" line=1 offset=18 implementation file="src/interfaces/repository.ts" line=3 offset=18

Workspace-wide symbol search by name. Takes a search string and returns matching symbols across all project files with their locations and kinds.

navto searchValue="User" file="src/app.ts" navto searchValue="handle" file="src/app.ts" maxResultCount=10 navto searchValue="Button" file="src/components/Button.tsx" currentFileOnly=true

Find every file that imports or references a given file. The reverse dependency graph for a single file.

fileReferences file="src/utils/helpers.ts" fileReferences file="src/types.ts"

Get the call hierarchy item(s) at a position — the entry point for call hierarchy queries. Returns the function/method name, kind, file location, and spans.

prepareCallHierarchy file="src/services/api.ts" line=10 offset=17 prepareCallHierarchy file="src/utils/helpers.ts" line=5 offset=17

Find all functions/methods that call the function at the given position. Answers "who calls this?"

provideCallHierarchyIncomingCalls file="src/services/api.ts" line=10 offset=17 provideCallHierarchyIncomingCalls file="src/utils/helpers.ts" line=5 offset=17

Find all functions/methods that the function at the given position calls. Answers "what does this call?"

provideCallHierarchyOutgoingCalls file="src/services/api.ts" line=10 offset=17 provideCallHierarchyOutgoingCalls file="src/utils/helpers.ts" line=5 offset=17

Get the tsconfig.json path, the full list of files in the project, and whether the language service is active.

projectInfo file="src/app.ts" projectInfo file="src/app.ts" needFileNameList=false

Get autocomplete suggestions at a position. Returns all possible completions with their kinds, sort text, and insert text. Useful for understanding what symbols, methods, or properties are available at a location.

completionInfo file="src/app.ts" line=10 offset=15 completionInfo file="src/app.ts" line=10 offset=15 prefix="get" completionInfo file="src/app.ts" line=10 offset=15 triggerCharacter="."

Get full details for specific completion entries — documentation, full type signature, JSDoc tags, and code actions (like auto-imports). Use as a follow-up tocompletionInfo.

completionEntryDetails file="src/app.ts" line=10 offset=15 entryNames=["map","filter"] completionEntryDetails file="src/app.ts" line=5 offset=10 entryNames=["useState"]

Get function/method signature information at a call site. Returns parameter names, types, and documentation for each overload. Use when the cursor is inside function call parentheses.

signatureHelp file="src/app.ts" line=12 offset=20 signatureHelp file="src/app.ts" line=12 offset=20 triggerReason={"kind":"invoked"}

Find all occurrences of a symbol within a file (or set of files). Distinguishes between read and write references. More efficient thanreferenceswhen you only need local occurrences.

documentHighlights file="src/app.ts" line=10 offset=5 documentHighlights file="src/app.ts" line=10 offset=5 filesToSearch=["src/app.ts","src/utils.ts"]

Discover what refactorings are available at a position or selection. Use before attempting a refactor to see what's possible. Returns a list of available refactors with their action names and descriptions.

getApplicableRefactors file="src/app.ts" startLine=10 startOffset=1 endLine=15 endOffset=1 getApplicableRefactors file="src/app.ts" startLine=8 startOffset=12 endLine=8 endOffset=35