MCP Zoomeye

🚀 ZoomEye MCP Server Guide

This guide provides a comprehensive overview of installing, configuring, and using the ZoomEye MCP Server, along with troubleshooting tips, advanced features, and contribution details.

🚀 Quick Start

📦 Installation

Install the ZoomEye MCP Server using npm:

npm install -g mcp-server-zoomeye

After installation, you can start the server and view the help information:

mcp-server-zoomeye --help

⚙️ Configuration

Set the ZOOM_EYE_API_KEY environment variable to ensure normal access to the ZoomEye API.

• On Unix/MacOS:

export ZOOM_EYE_API_KEY='your_api_key_here'

• On Windows:

set ZOOM_EYE_API_KEY=your_api_key_here

▶️ Starting the Server

Start the server and bind it to a specified port (default is 3000):

mcp-server-zoomeye --port 3000

💻 Usage Examples

🔍 Querying ZoomEye Data

Send a POST request to http://localhost:3000/mcp with the following request body:

{
  "name": "zoomeye_search",
  "arguments": {
    "qbase64": "app=\"Apache\"",
    "page": 1,
    "pagesize": 50
  }
}

📋 Example Response

{
  "id": "unique requestId",
  "status": "success",
  "result": {
    "data": [
      // Array of returned result data
    ],
    "total": 100,
    "page": 1,
    "pagesize": 50
  }
}

🔧 Debugging and Troubleshooting

🛠️ Using the MCP Inspector

Check the ZoomEye MCP Server:

npx @modelcontextprotocol/inspector uvx mcp-server-zoomeye

For local development:

cd path/to/servers/src/mcp_server_zoomeye
npx @modelcontextprotocol/inspector uv run mcp-server-zoomeye

❓ Common Issues

1. Authentication Errors
   • Ensure that the ZoomEye API key is correct and set as an environment variable.
   • Check if the key has expired or been revoked.
2. Connection Issues
   • Verify the network connection.
   • Confirm that the ZoomEye API is running normally.
3. No Results
   • The query may be too specific or contain syntax errors.
   • Try simplifying the query or using different search terms.
4. Rate Limitations
   • The ZoomEye API has different rate limits based on the account type.
   • Adjust the request frequency or upgrade your account to get higher limits.

✨ Features

🗃️ Cache Mechanism

The ZoomEye MCP Server provides the following caching features:

• Response caching based on query parameters
• Configurable cache duration (default is 1 hour)
• Set ignore_cache to true to bypass the cache

📋 Custom Fields

Specify the fields to be returned using the fields parameter:

{
  "name": "zoomeye_search",
  "arguments": {
    "qbase64": "app=\"Apache\"",
    "fields": "ip,port,domain,service,os,country,city"
  }
}

📄 Pagination

For a large number of results, use pagination:

{
  "name": "zoomeye_search",
  "arguments": {
    "qbase64": "app=\"Apache\"",
    "page": 2,
    "pagesize": 50
  }
}

🤝 Contribution and License

💻 Submitting Code

To contribute code, submit a PR on GitHub:

git clone git@github.com:yourusername/mcp-server-zoomeye.git
cd mcp-server-zoomeye
npm install

📄 License

This project is licensed under the Apache 2.0 license. For details, see the LICENSE file.

📞 Contact

If you have any questions or suggestions, please contact us:

• Email: support@zoomeye.com
• WeChat: zoomeye_support