mcp-server-requests

Instructions

Implementation Reference

• mcp_server_requests/server.py:393-451 (handler)

  Primary MCP tool handler for 'http_request'. Includes registration via @mcp.tool(), input schema via Annotated types, and execution logic calling mcp_http_request with user-agent and formatting.
  @mcp.tool() def http_request( url: Annotated[str, "(require) Target URL for the HTTP request"], *, method: Annotated[Literal['GET', 'POST', 'PUT', 'PATCH', 'DELETE'], "(optional, Defaults to \"GET\") HTTP method to use for the request"] = "GET", query: Annotated[Optional[Dict[str, str | int | float]], "(optional) Query parameters to append to the URL"] = None, headers: Annotated[Optional[Dict[str, str]], "(optional) Custom HTTP request headers"] = None, data: Annotated[Optional[str], "(optional) Text data to send in the request body. Cannot be used with 'json'"] = None, json: Annotated[Optional[Any], "(optional) JSON to send in the request body. Cannot be used with 'data'"] = None, ) -> str: """Execute an HTTP request with the specified method Function/Features: - Sends HTTP requests using any standard method (GET, POST, PUT, PATCH, DELETE) - Allows custom HTTP headers - Returns **complete** HTTP response including status, headers, and body Notes: - 'data' and 'json' parameters are mutually exclusive - use only one - When using 'json', the Content-Type header is automatically set to 'application/json' - When using 'data', you may need to set appropriate Content-Type header manually - Query parameters are URL-encoded automatically and appended to the URL - The response includes the full HTTP response with status line, all headers, and body Args: url (str): Target URL for the HTTP request. method ('GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE'], optional): HTTP method to use. Defaults to "GET". query ({ [string]: string | number }, optional): Query parameters to append to the URL. Values are automatically converted to strings. Example: {'key1': 'value1', 'key2': 2}, becomes "key1=value1&key2=2" appended to the URL. headers ({ [string]: string }, optional): Custom HTTP request headers. data (str, optional): Text data to send in the request body. Cannot be used with 'json'. json (Any JSON, optional): Data to serialize as JSON and send in the request body. Cannot be used with 'data'. Examples: // GET request (default method) http_request({url: "https://api.example.com/data"}) // GET request with query parameters http_request({url: "https://api.example.com/search", query: {"q": "test", "limit": 10}}) // POST request with JSON data http_request({url: "https://api.example.com/users", method: "POST", json: {"name": "John", "age": 30}}) // POST request with raw text data http_request({url: "https://api.example.com/log", method: "POST", data: "This is a log message"}) // PUT request http_request({url: "https://api.example.com/users/123", method: "PUT", json: {"name": "John Updated", "age": 31}}) // PATCH request http_request({url: "https://api.example.com/users/123", method: "PATCH", json: {"age": 31, "email": "new@example.com"}}) // DELETE request http_request({url: "https://api.example.com/users/123", method: "DELETE"}) // Request with custom headers http_request({url: "https://api.example.com/secure", method: "POST", headers: {"Authorization": "Bearer token"}, json: {"key": "value"}}) """ return mcp_http_request(method, url, query=query, data=data, json=json, headers=headers, user_agent=ua, force_user_agnet=ua_force)
• mcp_server_requests/server.py:121-164 (helper)

  Intermediate wrapper mcp_http_request: adds User-Agent header, calls core http_request, formats response or error.
  def mcp_http_request( method: str, url: str, *, query: Optional[dict] = None, data: Optional[str | bytes | bytearray] = None, json: Optional[dict] = None, headers: Optional[dict] = None, user_agent: Optional[str] = None, force_user_agnet: Optional[bool] = None, format_status: bool = True, format_headers: bool = True, return_content: Literal['raw', 'basic_clean', 'strict_clean', 'markdown'] = "raw", ) -> str: hs = {} if headers: hs.update(headers) if force_user_agnet: if user_agent: hs["User-Agent"] = user_agent else: if "User-Agent" not in hs and user_agent: hs["User-Agent"] = user_agent try: response = http_request( method, url, query=query, headers=hs, data=data, json_=json ) return format_response_result( response, format_status=format_status, format_headers=format_headers, return_content=return_content ) except Exception as e: return format_error_result(e)
• mcp_server_requests/request.py:83-164 (helper)

  Core low-level http_request implementation using Python's urllib.request. Handles URL/query, data/json body, headers, returns Response object. Includes error cases.
  def http_request( method: str, url: str, *, query: Optional[dict] = None, data: Optional[Union[str, bytes, bytearray]] = None, json_: Optional[dict] = None, headers: Optional[dict] = None ) -> Response: if headers is None: headers = {} if not isinstance(method, str): raise ArgumentError(f"http method must be a string, and must be one of {str(HTTP_METHODS)}") m, method = method, method.upper() if method not in HTTP_METHODS: raise ArgumentError(f"Invalid HTTP method: {m}, must be one of {str(HTTP_METHODS)}") if not isinstance(url, str): raise ArgumentError("URL must be a string") if data is not None and json_ is not None: raise ArgumentError("Both data and json cannot be provided at the same time") try: if query is not None: url = merge_query_to_url(url, query) except ArgumentError as e: raise e from e except Exception as e: raise ArgumentError("Failed to splicing URL and query") from e data_bytes = None if data is not None: if not isinstance(data, (str, bytes, bytearray)): raise ArgumentError("Data must be a string, bytes, or bytearray") elif isinstance(data, str): data_bytes = data.encode(encoding="utf-8") elif isinstance(data, bytearray): data_bytes = bytes(data) else: data_bytes = data elif json_ is not None: try: data_bytes = json.dumps(json_).encode(encoding="utf-8") except Exception as e: raise ArgumentError("Failed to serialize JSON data") from e if not url.startswith("http://") and not url.startswith("https://"): url = "https://" + url try: url = quote(url, safe=";/?:@&=+$,", encoding="utf-8") request = urllib.request.Request(url, method=method, headers=headers, data=data_bytes) response: http.client.HTTPResponse = urllib.request.urlopen(request) version = VERSION_MAP.get(response.version, "HTTP/1.1") status_code = response.status reason = response.reason response_headers = response.getheaders() content = response.read() result = Response(url, version, status_code, reason, response_headers, content) except urllib.error.HTTPError as e: if e.status is None: raise RequestError(f"Failed to send request, unknown error") from e version = "HTTP/1.1" status_code = e.status reason = e.reason response_headers = e.headers.items() content = e.read() result = Response(url, version, status_code, reason, response_headers, content) except urllib.error.URLError as e: raise RequestError(f"Failed to send request, {e.reason}") from e except Exception as e: raise RequestError(f"Failed to send request, {e}") from e return result
• mcp_server_requests/request.py:22-44 (schema)

  Response dataclass schema defining the structure of HTTP response objects used throughout the tool.
  @dataclass class Response: url: str version: str status_code: int reason: str headers: list[tuple[str, str]] content: str | bytes | bytearray _content_type: str | None = None @property def content_type(self) -> str: if self._content_type is None: for k, v in self.headers: if k.lower() == "content-type": self._content_type = v if self._content_type is None: self._content_type = "application/octet-stream" return self._content_type
• mcp_server_requests/server.py:44-99 (helper)

  Helper to format the final response string: handles content decoding, HTML cleaning/markdown conversion, assembles status/headers/body.
  def format_response_result( response: Response, *, format_status: bool | None = None, format_headers: bool | None = None, return_content: Literal["raw", "basic_clean", "strict_clean", "markdown"] = "raw", ) -> str: http_version = response.version status = response.status_code reason = response.reason headers = response.headers content = response.content content_type = response.content_type if not isinstance(content_type, str): content_type = 'application/octet-stream' if content_type.startswith("text/") or content_type.startswith("application/json"): try: if isinstance(content, (bytes, bytearray)): content = content.decode('utf-8') else: content = str(content) except UnicodeDecodeError as e: err_message = f"response content type is \"{content_type}\", but not utf-8 encoded'" raise ResponseError(response, err_message) from e except Exception as e: err_message = f"response content type is \"{content_type}\", but cannot be converted to a string" raise ResponseError(response, err_message) from e else: err_message = f'response content type is "{content_type}", cannot be converted to a string' raise ResponseError(response, err_message) if content_type.startswith("text/html"): if return_content == "raw": pass elif return_content == "basic_clean": content = clean_html(content, allowed_attrs=True) elif return_content == "strict_clean": content = clean_html(content, allowed_attrs=("id", "src", "href")) elif return_content == "markdown": content = html_to_markdown(content) strs = [] if format_status: strs.append(f"{http_version} {status} {reason}\r\n") if format_headers: response_header_str = "\r\n".join(f"{k}: {v}" for k, v in headers) strs.append(response_header_str) if len(strs) > 0: strs.append("\r\n\r\n") strs.append(content) return "\r\n".join(strs)