Socket MCP Server

A Model Context Protocol (MCP) server for Socket integration — lets AI assistants query dependency vulnerability scores and security metadata.

Why this repo exists

Socket MCP exposes Socket.dev's package-scoring API through the Model Context Protocol, so any MCP-aware AI assistant (Claude, VS Code Copilot, Cursor, Windsurf) can score a package, audit a package.json, or flag risky dependencies as part of a conversation. It ships as both a hosted public server (https://mcp.socket.dev/, no setup) and a self-hostable npm package, so you can choose between zero-friction and full data isolation.

✨ Features

• 🔍 Dependency Security Scanning - Get comprehensive security scores for npm, PyPI, cargo, Maven, NuGet, RubyGems, Go Modules, and more (supported ecosystems)
• 🌐 Public Hosted Service - Use our public server at https://mcp.socket.dev/; sign in once via OAuth, no self-hosting
• 🚀 Multiple Deployment Options - Run locally via stdio, HTTP, or use our service
• 🤖 AI Assistant Integration - Works seamlessly with Claude, VS Code Copilot, Cursor, and other MCP clients
• 📊 Batch Processing - Check multiple dependencies in a single request
• 🔒 OAuth Sign-In - Public server authenticates through your MCP client's OAuth flow; no API key to copy or manage

🛠️ This project is in early development and rapidly evolving.

Install

Option 1: Use the public Socket MCP server (recommended)

The easiest way to get started. The public server uses OAuth — your MCP client opens a browser to sign in to Socket on first connect; no API key to copy or manage. Click a button below to install in your favorite AI assistant.

Manual install — Claude Desktop / Claude Code

[!NOTE] Custom integrations are not available to all paid versions of Claude. Check here for more information.

1. In Claude Desktop, go to Settings > Developer > Edit Config.
2. Add the Socket MCP server configuration:

{
  "mcpServers": {
    "socket-mcp": {
      "type": "http",
      "url": "https://mcp.socket.dev/"
    }
  }
}

3. Save the configuration and restart Claude Desktop.
4. Now you can ask Claude "Check the security score for express version 4.18.2".

For Claude Code:

claude mcp add --transport http socket-mcp https://mcp.socket.dev/

Manual install — VS Code

# For VS Code with GitHub Copilot
code --add-mcp '{"name":"socket-mcp","type":"http","url":"https://mcp.socket.dev/"}'

Or add to .vscode/mcp.json:

{
  "servers": {
    "socket-mcp": {
      "type": "http",
      "url": "https://mcp.socket.dev/"
    }
  }
}

Manual install — Cursor

Cursor Settings → MCP → Add new MCP Server. Name socket-mcp, http type, URL https://mcp.socket.dev/.

{
  "mcpServers": {
    "socket-mcp": {
      "type": "http",
      "url": "https://mcp.socket.dev/"
    }
  }
}

Manual install — Windsurf

[!WARNING] Windsurf does not support http type MCP servers yet. Use the stdio configuration in Option 2 below.

{
  "mcpServers": {
    "socket-mcp": {
      "serverUrl": "https://mcp.socket.dev/mcp"
    }
  }
}

Manual install — Factory

Factory is an AI-powered software engineering platform. Install the Socket MCP server with the Factory CLI:

droid mcp add socket https://mcp.socket.dev/ --type http

To self-host with an API key instead, see Option 2 below and register the stdio command with droid mcp add.

Alternatively, type /mcp within the Factory droid to manage MCP servers from an interactive UI. Learn more in the Factory MCP documentation.

Option 2: Self-host the Socket MCP server

To run your own instance, create an API key first (only the packages:list permission scope is needed; see creating-and-managing-api-tokens).

Option 2a — Stdio mode (default)

Claude Code:

claude mcp add socket-mcp -e SOCKET_API_TOKEN="your-api-token-here" -- npx -y @socketsecurity/mcp@latest # socket-hook: allow npx

Most other MCP clients:

{
  "mcpServers": {
    "socket-mcp": {
      "command": "npx", // socket-hook: allow npx
      "args": ["@socketsecurity/mcp@latest"],
      "env": {
        "SOCKET_API_TOKEN": "your-api-token-here"
      }
    }
  }
}

Option 2b — HTTP mode

Run the server in HTTP mode using npx:

MCP_HTTP_MODE=true SOCKET_API_TOKEN=your-api-token npx @socketsecurity/mcp@latest --http # socket-hook: allow npx

Environment variables for HTTP mode:

Variable	Required	Default	Description
SOCKET_API_TOKEN	Required unless OAuth is enabled	None	Socket API token used for outbound API calls. Legacy aliases (SOCKET_API_KEY, SOCKET_CLI_API_TOKEN, SOCKET_CLI_API_KEY, SOCKET_SECURITY_API_TOKEN, SOCKET_SECURITY_API_KEY) are accepted via the fleet's getSocketApiToken() helper. If unset in OAuth-enabled HTTP mode, the validated incoming bearer token is forwarded upstream instead.
SOCKET_OAUTH_ISSUER	Set together with the two introspection vars to enable OAuth	None	OAuth issuer URL used for metadata discovery and incoming bearer-token validation.
SOCKET_OAUTH_INTROSPECTION_CLIENT_ID	With OAuth	None	Client ID used for token introspection.
SOCKET_OAUTH_INTROSPECTION_CLIENT_SECRET	With OAuth	None	Client secret used for token introspection.
SOCKET_OAUTH_REQUIRED_SCOPES	No	(none)	Space-delimited scopes required on incoming access tokens. When unset, no scope is enforced — any active token passes.
SOCKET_API_URL	No	Production Socket API URL, or localhost when SOCKET_DEBUG=true	Override the upstream Socket API endpoint. Useful for local development and testing.
SOCKET_DEBUG	No	false	Switches the default upstream Socket API endpoint to localhost when SOCKET_API_URL is unset.
TRUST_PROXY	No	false	When true, trust X-Forwarded-Host and X-Forwarded-Proto when building OAuth metadata URLs. Enable only behind a trusted reverse proxy that rewrites these headers.
MCP_PORT	HTTP mode only	3000	Port to bind the HTTP server to.

SOCKET_API_URL and SOCKET_DEBUG also apply in stdio mode.

To enable OAuth-backed auth for incoming MCP requests:

MCP_HTTP_MODE=true \
SOCKET_OAUTH_ISSUER=https://issuer.example.com \
SOCKET_OAUTH_INTROSPECTION_CLIENT_ID=your-client-id \
SOCKET_OAUTH_INTROSPECTION_CLIENT_SECRET=your-client-secret \
npx @socketsecurity/mcp@latest --http # socket-hook: allow npx

Add TRUST_PROXY=true only when the server is deployed behind a trusted reverse proxy or load balancer that normalizes the forwarded host and protocol headers.

Configure your MCP client to connect to the HTTP server:

{
  "mcpServers": {
    "socket-mcp": {
      "type": "http",
      "url": "http://localhost:3000"
    }
  }
}

Usage

Once installed, ask your AI assistant questions like:

• "Check the security score for express version 4.18.2"
• "Analyze the security of my package.json dependencies"
• "What are the vulnerability scores for react, lodash, and axios?"

Tools exposed

depscore

Query the Socket API for dependency scoring information. Returns supply chain, quality, maintenance, vulnerability, and license scores per package.

Parameter	Type	Required	Default	Description
packages	Array	✅ Yes	-	Array of package objects to analyze
packages[].ecosystem	String	No	"npm"	Package ecosystem. See Supported ecosystems below.
packages[].depname	String	✅ Yes	-	Name of the dependency/package
packages[].version	String	No	"unknown"	Version of the dependency

Supported ecosystems

Based on Socket's language support. The ecosystem parameter maps to PURL types:

Ecosystem	PURL type	Package managers	Maturity
JavaScript & TypeScript	npm	npm, yarn, pnpm, Bun, VLT	GA
Python	pypi	uv, pip, Poetry, Anaconda	GA
Go	golang	Go Modules	GA
Java / Scala / Kotlin	maven	Maven, Gradle, sbt	GA
Ruby	gem	Bundler	GA
.NET (C#, F#, VB)	nuget	NuGet	GA
Rust	cargo	cargo	GA
PHP	composer	Composer	Experimental
GitHub Actions	actions	GitHub Actions workflows	Experimental (workflow scanning, not package-level)

Example request:

{
  "packages": [
    { "ecosystem": "npm", "depname": "express", "version": "4.18.2" },
    { "ecosystem": "pypi", "depname": "fastapi", "version": "0.100.0" }
  ]
}

Sample response:

pkg:npm/express@4.18.2: supply_chain: 1.0, quality: 0.9, maintenance: 1.0, vulnerability: 1.0, license: 1.0
  Report: https://socket.dev/npm/package/express
pkg:pypi/fastapi@0.100.0: supply_chain: 1.0, quality: 0.95, maintenance: 0.98, vulnerability: 1.0, license: 1.0
  Report: https://socket.dev/pypi/package/fastapi

organizations

List the Socket organizations the authenticated user belongs to. Takes no parameters. Use it to discover the org_slug value that the org-scoped tools (alerts, threat_feed) require.

This tool needs a Socket API token. See Authentication for organization-scoped tools below.

alerts

List the latest security alerts for one Socket organization: supply-chain, vulnerability, quality, license, and maintenance issues across the org's monitored packages. Backed by GET /v0/orgs/{org_slug}/alerts. Results are paginated; pass the previous response's endCursor as cursor to fetch the next page.

Parameter	Type	Required	Default	Description
org_slug	String	✅ Yes	-	Organization slug (get it from the organizations tool)
severity	String	No	-	Comma-separated subset of low,medium,high,critical
status	String	No	-	open or cleared
category	String	No	-	Comma-separated subset of supplyChainRisk,maintenance,quality,license,vulnerability
artifact_type	String	No	-	Comma-separated ecosystems: npm,pypi,gem,maven,golang,nuget,cargo,chrome,openvsx
artifact_name	String	No	-	Restrict to a single package name
alert_type	String	No	-	Comma-separated Socket alert types (e.g. usesEval,unmaintained)
repo_slug	String	No	-	Comma-separated repository slugs
per_page	Integer	No	100	Results per page (1–5000)
cursor	String	No	-	Pagination cursor — the endCursor from a previous response

threat_feed

Look up items in a Socket organization's threat feed: packages recently flagged as malware, typosquats, obfuscated code, and similar. Backed by GET /v0/orgs/{org_slug}/threat-feed. The response carries a nextPageCursor; pass it as cursor to page forward.

Parameter	Type	Required	Default	Description
org_slug	String	✅ Yes	-	Organization slug (get it from the organizations tool)
filter	String	No	mal	Threat category: mal (malware), vuln, typ (typosquat), obf (obfuscated), mjo, kes, spy, etc.
ecosystem	String	No	-	Ecosystem: npm, pypi, gem, maven, golang, nuget, cargo, chrome, openvsx, huggingface
name	String	No	-	Filter by package name
version	String	No	-	Filter by package version
is_human_reviewed	Boolean	No	false	Only return human-reviewed items
sort	String	No	updated_at	Sort field: id, created_at, updated_at
direction	String	No	desc	Sort direction: asc, desc
updated_after	String	No	-	ISO timestamp; only items updated after this
created_after	String	No	-	ISO timestamp; only items created after this
per_page	Integer	No	30	Results per page (1–100)
cursor	String	No	-	Pagination cursor — the nextPageCursor from a previous response

package_files

List the files published in a package: a tree of paths and sizes for any package on a supported ecosystem. Use it to inspect what a dependency ships before installing it. Each entry prints a blob hash that package_file_contents and package_file_grep consume.

Parameter	Type	Required	Default	Description
ecosystem	String	No	npm	npm, pypi, gem, cargo, maven, golang, nuget, chrome, openvsx
depname	String	✅ Yes	-	Package name (e.g. lodash, @babel/core, org.springframework:spring-core)
version	String	✅ Yes	-	Package version
artifactId	String	No	-	Per-version disambiguator (PyPI filename, Maven artifact id, NuGet asset)
platform	String	No	-	Platform qualifier for per-OS/arch artifacts (e.g. openvsx linux-x64, darwin-arm64)

package_file_contents

Read a single file from a package. Pass the hash printed next to an entry in package_files output. Returns up to 1 MB of UTF-8 text; binary files return metadata only.

Parameter	Type	Required	Default	Description
hash	String	✅ Yes	-	Blob hash from package_files
path	String	No	-	File path, for display only; does not affect the lookup

package_file_grep

Search a single file from a package for lines matching a JavaScript regular expression, returning matches with line numbers (grep -n style). The file is fetched once per session and cached, so repeated greps on the same hash skip the network.

Parameter	Type	Required	Default	Description
hash	String	✅ Yes	-	Blob hash from package_files
pattern	String	✅ Yes	-	JavaScript regular expression (plain literals work too)
caseInsensitive	Boolean	No	false	Match case-insensitively
contextLines	Integer	No	0	Lines of context before and after each match (0–5)
maxMatches	Integer	No	100	Cap on matching lines returned (1–500)
path	String	No	-	File path, for display only; does not affect the lookup

Authentication for organization-scoped tools

depscore works without credentials on the public server. The organizations, alerts, threat_feed, and package_files tools call Socket's authenticated REST API, so they need a Socket API token.

How the server resolves a token depends on the transport:

• stdio mode reads one token at startup from the environment and uses it for every request. Set SOCKET_API_TOKEN. The server also accepts these aliases, in priority order: SOCKET_API_TOKEN → SOCKET_API_KEY → SOCKET_CLI_API_TOKEN → SOCKET_CLI_API_KEY → SOCKET_SECURITY_API_TOKEN → SOCKET_SECURITY_API_KEY. SOCKET_API_TOKEN is canonical; SOCKET_API_KEY is the alias most local setups already export. Because the process belongs to one user, this token is yours and scopes every tool to your account.
• HTTP mode scopes the organization tools to the caller, never to the server's own token. Send your Socket API token as an Authorization: Bearer <token> header on each request, or use an OAuth access token when the server runs OAuth. The server uses that per-request token for the Socket API calls it makes on your behalf. A shared deployment never answers organizations, alerts, threat_feed, or package_files with the operator's data: when a request carries no token, those tools return the auth-required error. depscore alone may fall back to the server's startup token, since package scores are the same for every caller.

Generate a token from the Socket dashboard under API tokens, then export it before launching the server:

export SOCKET_API_TOKEN="your-socket-api-token"

When no token is available, these tools return an authentication-required error explaining how to supply one for each transport.

Worked example: organization details and alerts

With SOCKET_API_KEY (or SOCKET_API_TOKEN) set, ask your assistant something like "show me the open critical alerts for my Socket org". Under the hood the assistant chains two tools:

1. Discover the org slug. Call organizations (no arguments). The server reads your token, calls GET /v0/organizations, and returns the organizations your token can see. Pick the slug you want, e.g. my-org.

2. Fetch alerts for that org. Call alerts with the slug and any filters:

   {
     "org_slug": "my-org",
     "severity": "high,critical",
     "status": "open"
   }

   The server calls GET /v0/orgs/my-org/alerts with the same token and returns the matching alerts plus pagination metadata. To page forward, pass the response's endCursor back as cursor.

The same token scopes every org-scoped tool, so threat_feed and package_files work the moment organizations confirms which slug the token belongs to.

Adjusting tool usage via client rules

You can customize how the MCP server interacts with your AI assistant by editing your client's rules file:

MCP Client	Rules File Location
Claude Desktop/Code	CLAUDE.md
VSCode Copilot	.github/copilot-instructions.md
Cursor	.cursor/rules

Example rule:

Always check dependency scores with the depscore tool when you add a new dependency. If the score is low, consider using an alternative library or writing the code yourself.

Claude Code Hook (Optional)

The repo ships an optional Claude Code hook that blocks high-risk packages before installation. When Claude Code runs an install command, the hook queries the public Socket MCP server at https://mcp.socket.dev/ and denies the install when the package's supply chain score is below 20 (known malware, typosquats, high-risk supply chain signals). No CLI to install — copy the file and wire it up; the public server signs in via OAuth on first use.

Supported ecosystems and package managers:

Ecosystem	Commands
npm	npm install, npm i, npm add, yarn add, pnpm add, bun add
PyPI	pip install, pip3 install, uv add, uv pip install, poetry add, pipenv install
Cargo	cargo add, cargo install
RubyGems	gem install, bundle add
Go	go get, go install
NuGet	dotnet add package, nuget install

Setup

Prerequisites: Node.js 22+.

1. Copy the whole socket-gate directory into your hooks folder. The bundled socket-gate.cjs is self-contained, so it runs without any dependencies beside it. From a checkout, run pnpm run build first to produce it; from a published install, copy from node_modules/@socketsecurity/mcp/:

mkdir -p ~/.claude/hooks
cp -R hooks/socket-gate ~/.claude/hooks/

2. Add to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "node ~/.claude/hooks/socket-gate/socket-gate.cjs"
          }
        ]
      }
    ]
  }
}

See hooks/socket-gate/README.md for the full reference.

How it works

The hook denies installation when supplyChain < 20, allows it otherwise — e.g. express/lodash/react (75–97) allow, browserlist (typosquat of browserslist, 15) and confirmed malware (0) block. Network, timeout, or parse errors all fail open, so a Socket outage will not block legitimate work.

Limitations

A best-effort guardrail, not a complete defense. Known gaps:

• Manifest edits + lockfile installs. If Claude edits a manifest directly (package.json, requirements.txt, Cargo.toml, Gemfile, go.mod, *.csproj) then runs a bare install (npm install, pip install -r requirements.txt, cargo build, bundle install, go mod tidy, dotnet restore), there is no package name on the command line to check.
• Package-manager invocations only. Direct downloads (curl | sh, wget), post-install scripts of already-accepted packages, and transitive dependencies are not re-checked.
• Indirect Claude paths. Sub-agents, MCP tools that shell out, and non-Bash tool calls are not covered unless the matcher is broadened.

Inspired by Jimmy Vo's dependency hook.

Development

Contributor commands

git clone https://github.com/SocketDev/socket-mcp.git
cd socket-mcp
npm install
npm run build

Run from source (stdio mode):

export SOCKET_API_TOKEN=your_api_token_here
node --experimental-strip-types index.ts

Or in HTTP mode:

MCP_HTTP_MODE=true SOCKET_API_TOKEN=your_api_token_here node --experimental-strip-types index.ts --http

Health check endpoint

When running in HTTP mode, GET /health returns:

{
  "status": "healthy",
  "service": "socket-mcp",
  "version": "0.0.18",
  "timestamp": "2025-06-17T20:45:22.059Z"
}

Suitable for Kubernetes liveness/readiness probes, Docker health checks, load balancers.

Troubleshooting

Q: The public server isn't responding — Check the URL https://mcp.socket.dev/, verify your MCP client configuration, restart your MCP client.

Q: Local server fails to start — Ensure Node.js 22+ is installed, check SOCKET_API_TOKEN is set, verify the API token has packages:list permission.

Q: Getting authentication errors with local server — Double-check your API key is valid, ensure packages:list scope, regenerate if needed.

Q: AI assistant can't find the depscore tool — Restart your MCP client after configuration changes, verify config is saved, check the server is running.

Getting help

• 📖 Socket Documentation
• 🐛 Report Issues
• 💬 Community Support

License

MIT