search-mcp by YouXam - MCP Server

Search MCP Server

A Model Context Protocol (MCP) server that provides web search functionality using the Coze API.

Features

Web search through Coze API workflow
Configurable result count and pagination
Automatic cleaning of special characters in search queries
Built-in API testing tool
TypeScript implementation with full type safety
Secure token management through environment variables

Installation

Install dependencies using pnpm:

pnpm install

Set up your environment variables:

cp .env.example .env
# Edit .env and add your COZE_TOKEN

Build the server:

pnpm run build

Configuration

Environment Variables

COZE_TOKEN (required): Your Coze API token
COZE_WORKFLOW_ID (optional): Custom workflow ID (defaults to 7515824930249211922)
COZE_API_BASE (optional): Custom API base URL

Getting a Coze Token

Visit Coze Platform
Create an account or sign in
Generate an API token in your dashboard
Set the token in your .env file

Usage

Running the Server

# Development mode
pnpm run dev

# Production mode
pnpm run start

Available Tools

1. web_search

Search the web for information.

Parameters:

query (string, required): Content to search for
num (integer, optional): Maximum number of results (1-100, default: 5)
start (integer, optional): Result offset for pagination (default: 0)

Example:

{
  "query": "latest AI developments",
  "num": 10,
  "start": 0
}

2. test_search_api

Test the Coze API connection and response structure.

Parameters:

query (string, optional): Test query (default: "ai")

Integration with Claude Desktop

Add the following configuration to your Claude Desktop config file (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "search-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/search-mcp/build/index.js"],
      "env": {
        "COZE_TOKEN": "your_coze_api_token_here"
      }
    }
  }
}

Important Notes:

Replace /absolute/path/to/search-mcp with the actual path to your project
Replace your_coze_api_token_here with your actual Coze API token
Restart Claude Desktop after adding the configuration

API Response Handling

The server automatically processes Coze API responses and formats them for optimal readability. The response structure is analyzed dynamically to provide the best possible output format.

Security

API tokens are never logged or exposed in responses
Environment variables are used for secure credential management
Input sanitization removes potentially harmful special characters

Development

Project Structure

search-mcp/
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript output
├── package.json          # Package configuration
├── tsconfig.json         # TypeScript configuration
├── .env.example          # Environment variables template
└── README.md            # This file

Building

pnpm run build

Testing

Use the built-in test tool to verify your API configuration:

Start the server
Use the test_search_api tool through your MCP client
Check the response structure and adjust formatting if needed

Troubleshooting

Common Issues

"COZE_TOKEN environment variable is required"
- Ensure you've set the COZE_TOKEN in your environment or .env file
HTTP errors from Coze API
- Verify your token is valid and has proper permissions
- Check if the workflow ID is correct
- Ensure you haven't exceeded rate limits
Server not appearing in Claude Desktop
- Verify the absolute path in your configuration
- Check that the server builds successfully
- Restart Claude Desktop after configuration changes

Debug Mode

Enable debug logging by setting the DEBUG environment variable:

DEBUG=1 pnpm run dev

License

MIT

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

Support

For issues and questions:

Check the troubleshooting section above
Review the MCP documentation
Create an issue in the repository