Spider Foot MCP Server

蜘蛛脚MCP代理

模型上下文协议（MCP）服务器的Node.js实现，将SpiderFoot的功能作为工具公开。该项目提供了一个MCP服务器和一个web客户端，用于与SpiderFoot web界面进行交互。

特性

• MCP服务器：通过模型上下文协议公开SpiderFoot功能
• web客户端：与SpiderFoot的web界面交互的程序化界面
• TypeScript支持：完全支持TypeScript，以获得更好的开发体验
• Docker支持：使用Docker轻松部署
• 模块化设计：易于扩展新功能

需求

• Node.js 18+（推荐20+）
• 本地SpiderFoot实例（Docker或直接安装）

- 默认web界面URL: http://127.0.0.1:5001

• Docker（可选，用于容器化部署）

设置

先决条件

1. 确保你有一个正在运行的SpiderFoot实例
2. 克隆此存储库：

   git clone https://github.com/yourusername/Spiderfoot-MCP-Agent.git
   cd Spiderfoot-MCP-Agent

安装

1. 安装依赖项：

   npm install

1. 配置环境：

   cp .env.example .env

编辑 .env 文件中包含您的SpiderFoot详细信息：

   # 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

用法

运行MCP服务器

开发模式（标准传输）

npm run dev

开发模式（HTTP传输）

npm run dev:http

生产建设

# Build the project
npm run build

# Start the server
npm start

使用Web客户端

该包包括一个web客户端，可用于以编程方式与SpiderFoot web界面进行交互。

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);
}

发展

建设项目

npm run typecheck
npm run build

从编译输出开始：

npm start            # stdio transport
npm run start:http   # HTTP transport (dist/index-http.js)

工具

服务器注册了以下工具：

• spiderfoot_ping –获取 /ping
• spiderfoot_modules –获取 /modules
• spiderfoot_event_types –获取 /eventtypes
• spiderfoot_scans –获取 /scanlist
• spiderfoot_scan_info –获取 /scanopts?id=
• spiderfoot_start_scan –帖子 /startscan （由守卫 ALLOW_START_SCAN)
• spiderfoot_scan_data –帖子 /scaneventresults
• spiderfoot_scan_data_unique –帖子 /scaneventresultsunique
• spiderfoot_scan_logs –帖子 /scanlog
• spiderfoot_export_json –帖子 /scanexportjsonmulti

危险的终点，如 /query 有意省略。

HTTP与stdio传输

• src/index.ts 使用stdio传输(StdioServerTransport).当IDE/代理启动您的进程并通过stdio进行通信时，这通常会使用。
• src/index-http.ts 使用流式HTTP传输，监听 /:port/mcp （默认端口 3000).将此用于基于远程/HTTP的MCP客户端。

HTTP端口的环境变量：

• MCP_HTTP_PORT （默认值： 3000)

Docker使用

此回购包括 Dockerfile 和 docker-compose.yml 在Docker中运行MCP服务器。

塑造形象：

docker build -t spiderfoot-mcp:local .

直接使用Docker运行：

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

或者使用Compose：

docker-compose up --build

编写文件(docker-compose.yml)配置：

• 服务： spiderfoot-mcp
• 端口映射： 3000:3000
• 默认env指向主机的SpiderFoot http://host.docker.internal:5001

笔记：

• 在Linux上，替换 host.docker.internal 使用您的主机IP或使用容器网络访问您的SpiderFoot服务。
• 确保SpiderFoot在港口可达 5001 从MCP容器内部。

环境变量

• SPIDERFOOT_BASE_URL -SpiderFoot web UI/API的基本URL。
• ALLOW_START_SCAN — true|false.启用/禁用 spiderfoot_start_scan 工具。默认 true.
• SPIDERFOOT_USER, SPIDERFOOT_PASS --如果在SpiderFoot中启用身份验证，则可选HTTP摘要凭据。
• MCP_HTTP_PORT --HTTP传输端口（如果使用 index-http.ts).默认 3000.

项目布局

• src/index.ts --MCP服务器（stdio传输）和工具注册。
• src/index-http.ts --具有会话管理的MCP服务器（HTTP传输）。
• src/spiderfootClient.ts --基于Axios的SpiderFoot端点客户端。
• Dockerfile --多级图像：构建TS→ 运行HTTP服务器。
• docker-compose.yml --使用env默认值运行容器。

与IDE和MCP兼容的客户端一起使用

本节提供了基于JSON的配置示例，用于从流行的IDE和工具连接此MCP服务器。支持两种运输方式：

1. Stdio传输：IDE启动您的本地进程
2. HTTP传输：IDE连接到正在运行的服务器 http://localhost:5002/mcp （带compose的Docker）或 http://localhost:3000/mcp 跑步时 npm run dev:http 本地

两者都可以使用；如果IDE支持，请添加两个单独的条目。

基于Docker的JSON（容器内的stdio）

如果您希望IDE在Docker中启动MCP服务器（而不需要长时间运行的编写服务），请在容器中使用此stdio配置。它运行stdio入口点(dist/index.js)并通过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": {}
    }
  }
}

复制粘贴克劳德桌面块（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"
    }
  }
}

笔记：

• 确保您已经构建了图像(docker build -t spiderfoot-mcp:local . 或 docker-compose build).
• 这种方法不会暴露端口；它通过Docker使用stdio(-i).
• 主机SpiderFoot URL通过以下方式传递 -e SPIDERFOOT_BASE_URL=http://host.docker.internal:5001.

常见配置示例

__Stdio（本地过程）__

{
  "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（连接到正在运行的服务器）__

{
  "mcpServers": {
    "spiderfoot-mcp-http": {
      "type": "http",
      "url": "http://localhost:5002/mcp"
    }
  }
}

笔记：

• 如果你愿意 npm start 而不是 tsx，更新 command/args 因此，例如。 command: "npm", args: ["run", "dev"].
• 在Windows上，保持正斜杠 cwd 或避开反睫毛（例如。， C:\\dev-env.local\\project-repos\\Spiderfoot-MCP-Agent).
• 确保SpiderFoot在 SPIDERFOOT_BASE_URL 从MCP服务器。

帆板运动

步骤：

1. 打开 Settings → MCP （或管理MCP服务器的工具/集成部分）。
2. 添加新的服务器条目。
3. 将上述JSON示例之一粘贴到您的MCP服务器配置中，并与任何现有的 mcpServers 条目。推荐选项：

- Docker标准： spiderfoot-mcp-docker-stdio （使用 command: docker) - HTTP： serverUrl 向 http://localhost:5002/mcp

1. 保存设置。
2. 如果使用HTTP模式（Docker Compose或 npm run dev:http).对于stdio，Windsurf将在需要时自动启动它。

Windsurf–选项2：通过服务器URL进行HTTP

{
  "mcpServers": {
    "spiderfoot-mcp-http": {
      "serverUrl": "http://localhost:5002/mcp"
    }
  }
}

Windsurf–选项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"
      ]
    }
  }
}

笔记：

• 确保您已经构建了图像(docker build -t spiderfoot-mcp:local . 或 docker-compose build).
• 这种方法不会暴露端口；它通过Docker使用stdio(-i).
• 主机SpiderFoot URL通过以下方式传递 -e SPIDERFOOT_BASE_URL=http://host.docker.internal:5001.

光标

步骤：

1. 打开MCP集成的光标设置。
2. 添加新的MCP服务器。
3. 使用Docker stdio JSON在容器中启动，或使用HTTP示例连接到 http://localhost:5002/mcp.
4. 通过列出MCP面板中的工具来保存和测试。

游标–选项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"
      ]
    }
  }
}

游标–选项2:HTTP

{
  "mcpServers": {
    "spiderfoot-mcp-http": {
      "type": "http",
      "url": "http://localhost:5002/mcp"
    }
  }
}

克劳德桌面

Claude Desktop读取一个JSON配置文件，其中可以包含 mcpServers 如上图所示。

典型配置文件位置：

• 窗户： %APPDATA%/Claude/claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

在顶层下添加或合并以下内容之一 mcpServers 如果您的扩展从对象中读取，或者在扩展特定密钥下读取（例如。， "cline.mcpServers").

克劳德桌面–选项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"
      ]
    }
  }
}

克劳德桌面–选项2:HTTP

{
  "mcpServers": {
    "spiderfoot-mcp-http": {
      "type": "http",
      "url": "http://localhost:5002/mcp"
    }
  }
}

VS代码（继续）

配置通常存储在VS代码中 settings.json.

常见位置：

• 窗户： %APPDATA%/Code/User/settings.json
• macOS： ~/Library/Application Support/Code/User/settings.json
• Linux： ~/.config/Code/User/settings.json

在顶层下添加或合并以下内容 mcpServers 如果您的扩展从对象中读取，或者在扩展特定密钥下读取（例如。， "continue.mcpServers").

VS代码（继续）-选项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代码（继续）-选项2:HTTP

{
  "mcpServers": {
    "spiderfoot-mcp-http": {
      "type": "http",
      "url": "http://localhost:5002/mcp"
    }
  }
}

笔记：

• 一些VS Code MCP扩展期望使用命名空间密钥（例如。， continue.mcpServers).如果是这样，请复制分配给的对象 mcpServers 在上面的命名空间设置中。
• 确保工作目录(cwd)点在 Spiderfoot-MCP-Agent/.

VS代码（临床）

VS代码（临床）-选项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代码（Cline）-选项2:HTTP

{
  "mcpServers": {
    "spiderfoot-mcp-http": {
      "type": "http",
      "url": "http://localhost:5002/mcp"
    }
  }
}

JetBrains（继续插件）

打开JetBrains IDE设置→ 继续→ MCP（或工具/集成），并使用上面显示的相同JSON条目添加服务器。

如果您的IDE存储JSON配置文件，请放置相同的文件 mcpServers 映射到该文件中，然后重新启动IDE。根据您的喜好使用stdio或HTTP条目。

JetBrains（续）-选项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（继续）-选项2:HTTP

{
  "mcpServers": {
    "spiderfoot-mcp-http": {
      "type": "http",
      "url": "http://localhost:5002/mcp"
    }
  }
}

泽德

打开Zed设置JSON（例如。， ~/.config/zed/settings.json)并添加MCP服务器映射。对于许多设置，根级别 mcpServers 客体作品；否则，请参阅Zed的MCP文档以获取确切密钥。

Zed–选项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–选项2:HTTP

{
  "mcpServers": {
    "spiderfoot-mcp-http": {
      "type": "http",
      "url": "http://localhost:5002/mcp"
    }
  }
}

MCP检验员（测试）

• 标准：运行 npm run dev 并将检查员指向该命令。
• HTTP：运行Docker Compose（或 npm run dev:http)并将Inspector连接到 http://localhost:5002/mcp.

备注

• 源文件位于 src/:

- src/index.ts –MCP服务器定义和工具注册（stdio）。 - src/index-http.ts –流式HTTP传输变体。 - src/spiderfootClient.ts –使用围绕SpiderFoot端点的HTTP包装器 axios.

• 该项目使用ESM("type": "module")，TypeScript 5和zod用于输入验证。
• 默认行为允许启动扫描；通过设置禁用 ALLOW_START_SCAN=false.