MCP Builder CLI

A command-line interface for generating Model Context Protocol (MCP) servers from API specifications. This package provides two separate tools:

1. MCP Builder CLI (mcp-builder) - Generate custom MCP servers from API specification documents
2. MCP API Server (mcp-api-server) - Make HTTP requests from AI assistants like Claude

What is this for?

This package contains two distinct tools that serve different purposes:

MCP Builder CLI (mcp-builder)

Generate custom MCP servers from API specification documents. This tool helps developers create MCP servers tailored to specific APIs.

MCP API Server (mcp-api-server)

Allow AI assistants like Claude to make HTTP requests (GET, POST, PUT, DELETE) to any web API directly. This acts as a bridge between AI assistants and web APIs, enabling them to:

• Fetch data from REST APIs
• Send data to web services
• Interact with online tools and platforms

For example, you could ask Claude to check the weather by making a request to a weather API, or ask it to shorten a URL using a URL shortening service.

Quickstart Guide

1. Using the Built-in API Server with Claude Desktop (Easiest)

First, configure Claude Desktop to use the built-in MCP API server:

1. Open Claude Desktop
2. Go to the MCP configuration file (usually located at ~/.config/claude/claude_desktop_config.json on Mac/Linux or %APPDATA%/Claude/claude_desktop_config.json on Windows)
3. Add this server configuration:

{
  "mcpServers": {
    "api-server": {
      "command": "npx",
      "args": ["mcp-api-server"]
    }
  }
}

1. Restart Claude Desktop
2. You can now use the API tools in Claude!

2. Running the API Server Directly

The easiest way to run the API server is using NPX (no installation required):

npx mcp-api-server

For development/testing, you might want to enable debug logging and allow localhost requests:

npx mcp-api-server --debug --allow-localhost

You can also run the server directly with Node:

node dist/src/index.js

With debug and localhost access:

node dist/src/index.js --debug --allow-localhost

3. Installing Globally

To install the tools globally on your system:

npm install -g mcp-builder

Then run the API server with:

mcp-api-server

4. Using with Claude

Once configured, you can ask Claude to make API requests:

"Can you get the latest news from https://api.example.com/news/latest?"

"Please post this data to my webhook: {"message": "Hello World"}"

Claude will automatically use the appropriate tool (api_get, api_post, etc.) based on what you're asking for.

Features

• 🚀 HTTP API Tools: GET, POST, PUT, DELETE request support
• 🔒 Security: Request validation with configurable security policies
• 📝 Logging: Comprehensive debug logging and request tracking
• ⚙️ Configurable: Flexible configuration via CLI args and environment variables
• 🛡️ Error Handling: Robust error handling with detailed error messages
• 🔄 Graceful Shutdown: Proper cleanup and shutdown handling

Installation

NPX (Recommended)

Run directly without installation:

npx mcp-builder

Global Installation

npm install -g mcp-builder
mcp-builder

Local Installation

npm install mcp-builder
npx mcp-builder

Usage

API Server Usage

# Start the API server
mcp-api-server

# Start with debug logging
mcp-api-server --debug

# Allow localhost requests (useful for development)
mcp-api-server --allow-localhost

# Allow private IP requests
mcp-api-server --allow-private-ips

# Show help
mcp-api-server --help

You can also run the API server directly with Node:

# Start the API server directly
node dist/src/index.js

# Start with debug logging
node dist/src/index.js --debug

# Allow localhost requests
node dist/src/index.js --allow-localhost

# Allow private IP requests
node dist/src/index.js --allow-private-ips

# Show help
node dist/src/index.js --help

Environment Variables

Configure the API server using environment variables:

# Server Configuration
API_TIMEOUT=60000          # Request timeout in milliseconds
ALLOW_LOCALHOST=true      # Allow requests to localhost (127.0.0.1)
ALLOW_PRIVATE_IPS=false   # Allow requests to private IP ranges
MAX_RESPONSE_LENGTH=100000 # Maximum response length in bytes
USER_AGENT="MyApp/1.0.0"   # Custom user agent string for requests

# Debug Configuration
DEBUG=true                # Enable detailed logging

MCP Builder CLI Usage

The MCP Builder CLI is used to generate custom MCP servers from API specification documents:

# Generate an MCP server from an API specification
mcp-builder generate <api-spec.md> <output-directory>

# Validate an API specification file
mcp-builder validate <api-spec.md>

# Show help
mcp-builder --help

# Show help for a specific command
mcp-builder help generate

Configuration Options

| CLI Option | Environment Variable | Default | Description | |------------|---------------------|---------|-------------| | --debug | DEBUG | false | Enable debug logging | | --allow-localhost | ALLOW_LOCALHOST | false | Allow requests to localhost | | --allow-private-ips | ALLOW_PRIVATE_IPS | false | Allow requests to private IPs | | N/A | API_TIMEOUT | 30000 | Request timeout in milliseconds | | N/A | MAX_RESPONSE_LENGTH | 50000 | Maximum response length in bytes | | N/A | USER_AGENT | MCP-API-Server/1.0.0 | Custom user agent string |

Available Tools

The API server provides the following MCP tools that Claude or other MCP clients can use:

api_get

Make an HTTP GET request to retrieve data from a URL.

Parameters:

• url (string): The URL to request data from
• headers (object, optional): HTTP headers to include in the request

Example usage with Claude:

"Can you fetch the JSON data from https://api.example.com/users?"

api_post

Make an HTTP POST request to send data to a URL.

Parameters:

• url (string): The URL to send data to
• body (string or object, optional): The data to send
• headers (object, optional): HTTP headers to include in the request

Example usage with Claude:

"Please post this JSON to my webhook: {"name": "John", "age": 30}"

api_put

Make an HTTP PUT request to update data at a URL.

Parameters:

• url (string): The URL to update data at
• body (string or object, optional): The updated data
• headers (object, optional): HTTP headers to include in the request

Example usage with Claude:

"Update my user profile with this data: {"name": "John Smith", "age": 31}"

api_delete

Make an HTTP DELETE request to remove data at a URL.

Parameters:

• url (string): The URL to delete data from
• headers (object, optional): HTTP headers to include in the request

Example usage with Claude:

"Please delete the user with ID 123 from https://api.example.com/users/123"

MCP Client Configuration

To use this server with an MCP client, add it to your MCP configuration:

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "api-server": {
      "command": "npx",
      "args": ["mcp-api-server"]
    }
  }
}

With Custom Configuration

{
  "mcpServers": {
    "api-server": {
      "command": "npx",
      "args": ["mcp-api-server", "--debug", "--allow-localhost"]
    }
  }
}

You can also run the server directly with Node:

{
  "mcpServers": {
    "api-server": {
      "command": "node",
      "args": ["dist/src/index.js", "--debug", "--allow-localhost"]
    }
  }
}

Security Considerations

• By default, requests to localhost and private IP ranges are blocked to prevent SSRF attacks
• Only enable --allow-localhost and --allow-private-ips in trusted environments
• The server validates all requests and sanitizes responses
• Request timeouts prevent hanging connections
• Response size limits prevent memory exhaustion

Error Handling

The server provides detailed error messages for:

• Invalid URLs
• Network timeouts
• JSON parsing errors
• Validation failures
• HTTP errors

All errors are logged with timestamps and context for debugging.

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

• Report issues: GitHub Issues
• Documentation: GitHub Repository

Installation

NPX (Recommended)

Run directly without installation:

npx mcp-builder

Global Installation

npm install -g mcp-builder
mcp-builder

Local Installation

npm install mcp-builder
npx mcp-builder

Usage

Basic Usage

# Start the server
mcp-api-server

# Start with debug logging
mcp-api-server --debug

# Allow localhost requests (useful for development)
mcp-api-server --allow-localhost

# Allow private IP requests
mcp-api-server --allow-private-ips

# Show help
mcp-api-server --help

You can also run the server directly with Node:

# Start the server
node dist/src/index.js

# Start with debug logging
node dist/src/index.js --debug

# Allow localhost requests
node dist/src/index.js --allow-localhost

# Allow private IP requests
node dist/src/index.js --allow-private-ips

# Show help
node dist/src/index.js --help

Environment Variables

Configure the server using environment variables:

# Server Configuration
API_TIMEOUT=60000          # Request timeout in milliseconds
ALLOW_LOCALHOST=true      # Allow requests to localhost (127.0.0.1)
ALLOW_PRIVATE_IPS=false   # Allow requests to private IP ranges
MAX_RESPONSE_LENGTH=100000 # Maximum response length in bytes
USER_AGENT="MyApp/1.0.0"   # Custom user agent string for requests

# Debug Configuration
DEBUG=true                # Enable detailed logging

Configuration Options

| CLI Option | Environment Variable | Default | Description | |------------|---------------------|---------|-------------| | --debug | DEBUG | false | Enable debug logging | | --allow-localhost | ALLOW_LOCALHOST | false | Allow requests to localhost | | --allow-private-ips | ALLOW_PRIVATE_IPS | false | Allow requests to private IPs | | N/A | API_TIMEOUT | 30000 | Request timeout in milliseconds | | N/A | MAX_RESPONSE_LENGTH | 50000 | Maximum response length in bytes | | N/A | USER_AGENT | MCP-API-Server/1.0.0 | Custom user agent string |

Available Tools

The server provides the following MCP tools that Claude or other MCP clients can use:

api_get

Make an HTTP GET request to retrieve data from a URL.

Parameters:

• url (string): The URL to request data from
• headers (object, optional): HTTP headers to include in the request

Example usage with Claude:

"Can you fetch the JSON data from https://api.example.com/users?"

api_post

Make an HTTP POST request to send data to a URL.

Parameters:

• url (string): The URL to send data to
• body (string or object, optional): The data to send
• headers (object, optional): HTTP headers to include in the request

Example usage with Claude:

"Please post this JSON to my webhook: {"name": "John", "age": 30}"

api_put

Make an HTTP PUT request to update data at a URL.

Parameters:

• url (string): The URL to update data at
• body (string or object, optional): The updated data
• headers (object, optional): HTTP headers to include in the request

Example usage with Claude:

"Update my user profile with this data: {"name": "John Smith", "age": 31}"

api_delete

Make an HTTP DELETE request to remove data at a URL.

Parameters:

• url (string): The URL to delete data from
• headers (object, optional): HTTP headers to include in the request

Example usage with Claude:

"Please delete the user with ID 123 from https://api.example.com/users/123"

MCP Client Configuration

To use this server with an MCP client, add it to your MCP configuration:

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "api-server": {
      "command": "npx",
      "args": ["mcp-api-server"]
    }
  }
}

With Custom Configuration

{
  "mcpServers": {
    "api-server": {
      "command": "npx",
      "args": ["mcp-api-server", "--debug", "--allow-localhost"]
    }
  }
}

Security Considerations

• By default, requests to localhost and private IP ranges are blocked to prevent SSRF attacks
• Only enable --allow-localhost and --allow-private-ips in trusted environments
• The server validates all requests and sanitizes responses
• Request timeouts prevent hanging connections
• Response size limits prevent memory exhaustion

Error Handling

The server provides detailed error messages for:

• Invalid URLs
• Network timeouts
• JSON parsing errors
• Validation failures
• HTTP errors

All errors are logged with timestamps and context for debugging.

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

• Report issues: GitHub Issues
• Documentation: GitHub Repository