justoneapi

JustOneAPI MCP Server exposes JustOneAPI endpoints as MCP tools, returning the original raw JSON responses from upstream APIs. This preserves data fidelity by avoiding field parsing or restructuring, making it ideal for AI agents and development workflows that rely on unmodified upstream data. Tools are organized under the server name (e.g., unified_search_v1) and other platform-specific actions, each returning the exact upstream JSON payload. To use it, configure your MCP host (e.g., Claude Desktop or Cursor) to run the justoneapi-mcp server and supply your JustOneAPI API token via the JUSTONEAPI_TOKEN environment variable. Once configured, you can invoke the available tools to query JustOneAPI endpoints and receive raw responses for further processing or direct passthrough to the user.

The most prominent tool is unified_search_v1, which performs a cross-platform search across multiple Chinese social media and news sources (Weibo, WeChat, Zhihu, Douyin, Xiaohongshu, Bilibili, Kuaishou, and News). You can query with natural language, and the MCP host will format the request, respect date ranges (UTC+8), and handle pagination with nextCursor. Other tools follow the naming convention {platform}{action}{version}, enabling platform-specific actions such as video search or item lookup. The MCP server returns the raw JSON from upstream, so downstream applications can display or rehydrate data exactly as provided by JustOneAPI.

To discover all tools, issue the host's tool listing command (for example, Please list all available tools from justoneapi-mcp) and then call the specific tool you need with its required parameters. The included documentation in TOOLS.md (referenced in the README) provides schemas, examples, and validation details for each tool.

Prerequisites:

• Node.js (preferred) and npm installed on your machine
• Basic Git knowledge
• A JustOneAPI API token

Option A: Quick npx setup (no installation needed)

1. Ensure Node.js and npm are installed. Then you can run the MCP server directly via npx, which downloads the package on demand.

2. Configure your MCP host to use the following server configuration (example for Claude Desktop):

{
  "mcpServers": {
    "justoneapi": {
      "command": "npx",
      "args": ["-y", "justoneapi-mcp"],
      "env": {
        "JUSTONEAPI_TOKEN": "your_actual_token_here"
      }
    }
  }
}

Option B: Global npm installation

1. Install the MCP package globally:

npm install -g justoneapi-mcp

2. Configure Claude Desktop (or your MCP host) to use the global command:

{
  "mcpServers": {
    "justoneapi": {
      "command": "justoneapi-mcp",
      "env": {
        "JUSTONEAPI_TOKEN": "your_actual_token_here"
      }
    }
  }
}

Option C: Local development (from source)

1. Clone the repository and install dependencies:

git clone <repository>
cd justoneapi-mcp
npm install

2. Build if required and run the server locally (depending on the package setup):

npm run build

3. Then configure Claude Desktop to point to the built index.js (absolute path) with Node as the command and appropriate env var:

{
  "mcpServers": {
    "justoneapi": {
      "command": "node",
      "args": ["/absolute/path/to/justoneapi-mcp/dist/index.js"],
      "env": {
        "JUSTONEAPI_TOKEN": "your_actual_token_here"
      }
    }
  }
}

Note: Always replace your_actual_token_here with your real JustOneAPI token. The token is required for authentication with JustOneAPI and is the only sensitive piece you need to provide for operation.

Tips and troubleshooting:

• Ensure JUSTONEAPI_TOKEN is set in the environment configured for the MCP host. Without a valid token, requests to JustOneAPI will fail.
• The MCP server preserves upstream JSON exactly as received; if you need to debug, inspect the raw responses from the upstream endpoint in your MCP host's output.
• When using npx, you may experience occasional network or registry lag; using a global npm installation is a common workaround for production setups.
• For discovery and documentation, refer to TOOLS.md in the repository for a complete list of tools, parameters, and validation schemas.
• If you rotate tokens, update the config in your MCP host accordingly and restart the host to pick up changes.