SpiderFoot MCP Agent
A Node.js implementation of the Model Context Protocol (MCP) server that exposes SpiderFoot's functionality as tools. This project provides both an MCP server and a web client for interacting with the SpiderFoot web interface.
Features
- MCP Server: Exposes SpiderFoot functionality through the Model Context Protocol
- Web Client: Programmatic interface to interact with SpiderFoot's web interface
- TypeScript Support: Full TypeScript support for better development experience
- Docker Support: Easy deployment using Docker
- Modular Design: Easy to extend with new functionality
Requirements
- Node.js 18+ (recommended 20+)
- A local SpiderFoot instance (Docker or direct installation)
- Default web interface URL:
http://127.0.0.1:5001
- Default web interface URL:
- Docker (optional, for containerized deployment)
Setup
Prerequisites
- Ensure you have a running instance of SpiderFoot
- Clone this repository:
git clone https://github.com/yourusername/Spiderfoot-MCP-Agent.git cd Spiderfoot-MCP-Agent
Installation
-
Install dependencies:
npm install -
Configure environment:
cp .env.example .envEdit the
.envfile with your SpiderFoot details:# Base URL of your SpiderFoot instance SPIDERFOOT_BASE_URL=http://127.0.0.1:5001 # Authentication (if enabled in SpiderFoot) # SPIDERFOOT_USER=username # SPIDERFOOT_PASS=password # Allow starting scans through the API ALLOW_START_SCAN=true
Usage
Running the MCP Server
Development Mode (stdio transport)
npm run dev
Development Mode (HTTP transport)
npm run dev:http
Production Build
# Build the project
npm run build
# Start the server
npm start
Using the Web Client
The package includes a web client that can be used to interact with the SpiderFoot web interface programmatically.
import { SpiderFootWebClient } from './spiderfoot-web-client.js';
// Create a new client instance
const client = new SpiderFootWebClient('http://127.0.0.1:5001');
// List all scans
const scans = await client.listScans();
console.log('Existing scans:', scans);
// Start a new scan
try {
const result = await client.startScan('example.com', ['type_DNS_TEXT'], 'domain', 'test-scan');
console.log('Scan started:', result);
} catch (error) {
console.error('Failed to start scan:', error);
}
Development
Building the Project
npm run typecheck
npm run build
Start from compiled output:
npm start # stdio transport
npm run start:http # HTTP transport (dist/index-http.js)
Tools
The server registers the following tools:
spiderfoot_ping– GET/pingspiderfoot_modules– GET/modulesspiderfoot_event_types– GET/eventtypesspiderfoot_scans– GET/scanlistspiderfoot_scan_info– GET/scanopts?id=<sid>spiderfoot_start_scan– POST/startscan(guarded byALLOW_START_SCAN)spiderfoot_scan_data– POST/scaneventresultsspiderfoot_scan_data_unique– POST/scaneventresultsuniquespiderfoot_scan_logs– POST/scanlogspiderfoot_export_json– POST/scanexportjsonmulti
Dangerous endpoints like /query are intentionally omitted.
HTTP vs stdio transports
src/index.tsuses the stdio transport (StdioServerTransport). This is commonly used when an IDE/agent launches your process and communicates via stdio.src/index-http.tsuses the Streamable HTTP transport, listening on/:port/mcp(default port3000). Use this for remote/HTTP-based MCP clients.
Environment variable for HTTP port:
MCP_HTTP_PORT(default:3000)
Docker usage
This repo includes a Dockerfile and docker-compose.yml to run the MCP server in Docker.
Build the image:
docker build -t spiderfoot-mcp:local .
Run with Docker directly:
docker run --rm -p 3000:3000 \
-e SPIDERFOOT_BASE_URL=http://host.docker.internal:5001 \
-e ALLOW_START_SCAN=true \
-e MCP_HTTP_PORT=3000 \
--name spiderfoot-mcp spiderfoot-mcp:local
Or with Compose:
docker-compose up --build
Compose file (docker-compose.yml) configures:
- Service:
spiderfoot-mcp - Port mapping:
3000:3000 - Default env points to your host’s SpiderFoot at
http://host.docker.internal:5001
Notes:
- On Linux, replace
host.docker.internalwith your host IP or use the container network to reach your SpiderFoot service. - Ensure SpiderFoot is reachable on port
5001from inside the MCP container.
Environment variables
SPIDERFOOT_BASE_URL— Base URL of your SpiderFoot web UI/API.ALLOW_START_SCAN—true|false. Enables/disablesspiderfoot_start_scantool. Defaulttrue.SPIDERFOOT_USER,SPIDERFOOT_PASS— Optional HTTP Digest credentials if you enable auth in SpiderFoot.MCP_HTTP_PORT— Port for HTTP transport (if usingindex-http.ts). Default3000.
Project layout
src/index.ts— MCP server (stdio transport) and tool registration.src/index-http.ts— MCP server (HTTP transport) with session management.src/spiderfootClient.ts— Axios-based client for SpiderFoot endpoints.Dockerfile— Multi-stage image: builds TS → runs HTTP server.docker-compose.yml— Runs container with env defaults.
Using with IDEs and MCP-compatible clients
This section provides JSON-based configuration examples for connecting this MCP server from popular IDEs and tools. Two transport modes are supported:
- Stdio transport: the IDE launches your local process
- HTTP transport: the IDE connects to a running server at
http://localhost:5002/mcp(Docker with compose) orhttp://localhost:3000/mcpwhen runningnpm run dev:httplocally
You can use both; add two separate entries if your IDE supports it.
Docker-based JSON (stdio inside container)
If you prefer your IDE to launch the MCP server inside Docker (without needing a long-running compose service), use this stdio-in-container configuration. It runs the stdio entrypoint (dist/index.js) and communicates over stdin/stdout.
{
"mcpServers": {
"spiderfoot-mcp-docker-stdio": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--add-host=host.docker.internal:host-gateway",
"-e",
"SPIDERFOOT_BASE_URL=http://host.docker.internal:5001",
"spiderfoot-mcp:local",
"node",
"dist/index.js"
],
"env": {}
}
}
}
Copy-paste Claude Desktop block (Docker stdio + HTTP):
{
"mcpServers": {
"spiderfoot-mcp-docker-stdio": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--add-host=host.docker.internal:host-gateway",
"-e",
"SPIDERFOOT_BASE_URL=http://host.docker.internal:5001",
"spiderfoot-mcp:local",
"node",
"dist/index.js"
]
},
"spiderfoot-mcp-http": {
"type": "http",
"url": "http://localhost:5002/mcp"
}
}
}
Notes:
- Make sure you have built the image (
docker build -t spiderfoot-mcp:local .ordocker-compose build). - This approach does not expose a port; it uses stdio via Docker (
-i). - The host SpiderFoot URL is passed via
-e SPIDERFOOT_BASE_URL=http://host.docker.internal:5001.
Common configuration examples
Stdio (local process)
{
"mcpServers": {
"spiderfoot-mcp-stdio": {
"type": "stdio",
"command": "node",
"args": [
"./node_modules/tsx/dist/cli.mjs",
"src/index.ts"
],
"cwd": "C:/dev-env.local/project-repos/Spiderfoot-MCP-Agent",
"env": {
"SPIDERFOOT_BASE_URL": "http://127.0.0.1:5001",
"ALLOW_START_SCAN": "true"
}
}
}
}
HTTP (connect to running server)
{
"mcpServers": {
"spiderfoot-mcp-http": {
"type": "http",
"url": "http://localhost:5002/mcp"
}
}
}
Notes:
- If you prefer
npm startinstead oftsx, updatecommand/argsaccordingly, e.g.command: "npm", args: ["run", "dev"]. - On Windows, keep forward slashes in
cwdor escape backslashes (e.g.,C:\\dev-env.local\\project-repos\\Spiderfoot-MCP-Agent). - Ensure SpiderFoot is reachable at
SPIDERFOOT_BASE_URLfrom the MCP server.
Windsurf
Steps:
- Open
Settings→MCP(or Tools/Integrations section that manages MCP servers). - Add a new server entry.
- Paste one of the JSON examples above into your MCP server configuration, merging with any existing
mcpServersentries. Recommended options:- Docker stdio:
spiderfoot-mcp-docker-stdio(usescommand: docker) - HTTP:
serverUrltohttp://localhost:5002/mcp
- Docker stdio:
- Save settings.
- Start the server if using HTTP mode (Docker Compose or
npm run dev:http). For stdio, Windsurf will launch it automatically when needed.
Windsurf – Option 2: HTTP via serverUrl
{
"mcpServers": {
"spiderfoot-mcp-http": {
"serverUrl": "http://localhost:5002/mcp"
}
}
}
Windsurf – Option 1: Docker stdio
{
"mcpServers": {
"spiderfoot-mcp-docker-stdio": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--add-host=host.docker.internal:host-gateway",
"-e",
"SPIDERFOOT_BASE_URL=http://host.docker.internal:5001",
"spiderfoot-mcp:local",
"node",
"dist/index.js"
]
}
}
}
Notes:
- Make sure you have built the image (
docker build -t spiderfoot-mcp:local .ordocker-compose build). - This approach does not expose a port; it uses stdio via Docker (
-i). - The host SpiderFoot URL is passed via
-e SPIDERFOOT_BASE_URL=http://host.docker.internal:5001.
Cursor
Steps:
- Open Cursor settings for MCP integrations.
- Add a new MCP server.
- Use the Docker stdio JSON to launch in a container, or the HTTP example to connect to
http://localhost:5002/mcp. - Save and test by listing tools from the MCP panel.
Cursor – Option 1: Docker stdio
{
"mcpServers": {
"spiderfoot-mcp-docker-stdio": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--add-host=host.docker.internal:host-gateway",
"-e",
"SPIDERFOOT_BASE_URL=http://host.docker.internal:5001",
"spiderfoot-mcp:local",
"node",
"dist/index.js"
]
}
}
}
Cursor – Option 2: HTTP
{
"mcpServers": {
"spiderfoot-mcp-http": {
"type": "http",
"url": "http://localhost:5002/mcp"
}
}
}
Claude Desktop
Claude Desktop reads a JSON configuration file that can include the mcpServers map shown above.
Typical configuration file locations:
- Windows:
%APPDATA%/Claude/claude_desktop_config.json - macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Linux:
~/.config/Claude/claude_desktop_config.json
Add or merge one of the following under a top-level mcpServers object if your extension reads from it, or under the extension-specific key (e.g., "cline.mcpServers").
Claude Desktop – Option 1: Docker stdio
{
"mcpServers": {
"spiderfoot-mcp-docker-stdio": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--add-host=host.docker.internal:host-gateway",
"-e",
"SPIDERFOOT_BASE_URL=http://host.docker.internal:5001",
"spiderfoot-mcp:local",
"node",
"dist/index.js"
]
}
}
}
Claude Desktop – Option 2: HTTP
{
"mcpServers": {
"spiderfoot-mcp-http": {
"type": "http",
"url": "http://localhost:5002/mcp"
}
}
}
VS Code (Continue)
Configuration is typically stored in VS Code settings.json.
Common locations:
- Windows:
%APPDATA%/Code/User/settings.json - macOS:
~/Library/Application Support/Code/User/settings.json - Linux:
~/.config/Code/User/settings.json
Add or merge the following under a top-level mcpServers object if your extension reads from it, or under the extension-specific key (e.g., "continue.mcpServers").
VS Code (Continue) – Option 1: Docker stdio
{
"mcpServers": {
"spiderfoot-mcp-docker-stdio": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--add-host=host.docker.internal:host-gateway",
"-e",
"SPIDERFOOT_BASE_URL=http://host.docker.internal:5001",
"spiderfoot-mcp:local",
"node",
"dist/index.js"
]
}
}
}
VS Code (Continue) – Option 2: HTTP
{
"mcpServers": {
"spiderfoot-mcp-http": {
"type": "http",
"url": "http://localhost:5002/mcp"
}
}
}
Notes:
- Some VS Code MCP extensions expect a namespaced key (e.g.,
continue.mcpServers). If so, copy the object assigned tomcpServersabove into that namespaced setting. - Ensure the working directory (
cwd) points atSpiderfoot-MCP-Agent/.
VS Code (Cline)
VS Code (Cline) – Option 1: Docker stdio
{
"mcpServers": {
"spiderfoot-mcp-docker-stdio": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--add-host=host.docker.internal:host-gateway",
"-e",
"SPIDERFOOT_BASE_URL=http://host.docker.internal:5001",
"spiderfoot-mcp:local",
"node",
"dist/index.js"
]
}
}
}
VS Code (Cline) – Option 2: HTTP
{
"mcpServers": {
"spiderfoot-mcp-http": {
"type": "http",
"url": "http://localhost:5002/mcp"
}
}
}
JetBrains (Continue plugin)
Open your JetBrains IDE settings → Continue → MCP (or Tools/Integrations) and add a server using the same JSON entries shown above.
If your IDE stores a JSON configuration file, place the same mcpServers map in that file and restart the IDE. Use stdio or HTTP entries per your preference.
JetBrains (Continue) – Option 1: Docker stdio
{
"mcpServers": {
"spiderfoot-mcp-docker-stdio": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--add-host=host.docker.internal:host-gateway",
"-e",
"SPIDERFOOT_BASE_URL=http://host.docker.internal:5001",
"spiderfoot-mcp:local",
"node",
"dist/index.js"
]
}
}
}
JetBrains (Continue) – Option 2: HTTP
{
"mcpServers": {
"spiderfoot-mcp-http": {
"type": "http",
"url": "http://localhost:5002/mcp"
}
}
}
Zed
Open Zed settings JSON (e.g., ~/.config/zed/settings.json) and add an MCP servers map. For many setups, a root-level mcpServers object works; otherwise, consult Zed’s MCP documentation for the exact key.
Zed – Option 1: Docker stdio
{
"mcpServers": {
"spiderfoot-mcp-docker-stdio": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--add-host=host.docker.internal:host-gateway",
"-e",
"SPIDERFOOT_BASE_URL=http://host.docker.internal:5001",
"spiderfoot-mcp:local",
"node",
"dist/index.js"
]
}
}
}
Zed – Option 2: HTTP
{
"mcpServers": {
"spiderfoot-mcp-http": {
"type": "http",
"url": "http://localhost:5002/mcp"
}
}
}
MCP Inspector (testing)
- Stdio: run
npm run devand point Inspector to that command. - HTTP: run Docker Compose (or
npm run dev:http) and connect Inspector tohttp://localhost:5002/mcp.
Notes
- Source files are in
src/:src/index.ts– MCP server definition and tool registration (stdio).src/index-http.ts– Streamable HTTP transport variant.src/spiderfootClient.ts– HTTP wrapper around SpiderFoot endpoints usingaxios.
- The project uses ESM (
"type": "module"), TypeScript 5, and zod for input validation. - Default behavior allows starting scans; disable by setting
ALLOW_START_SCAN=false.