mcp-api-test 0.1.0

MCP server for testing REST API with built-in assertions

api-test-mcp

MCP server for REST API testing with assertions. Provides a test_api tool that accepts either a cURL command or structured request fields, runs the request, and validates against expected status codes and response fields

Prerequisites

• Python >= 3.10
• pip or uv for package installation

Install

From PyPI

pip install mcp-api-test

From source

git clone [e-mail]:ryaneatfood/mcp-api-testing.git

# change the directory
cd api-test-mcp

# install from source
pip install -e .

This registers the api-test-mcp CLI command on your PATH. Verify with:

which api-test-mcp

Testing with MCP Inspector

The MCP Inspector provides a browser-based UI to verify your server connects and responds correctly before wiring it into a client.

Make sure api-test-mcp is installed on your PATH (see Install), then run:

npx @modelcontextprotocol/inspector

This launches the inspector and opens http://localhost:5173 in your browser. From the UI:

1. Set Transport Type to STDIO
2. Set Command to api-test-mcp
3. Leave Arguments empty (your server needs none)
4. Click Connect

When the connection succeeds, the status badge changes to Connected and the inspector lists the test_api tool under the Tools tab. You can click the tool to open a form and run test calls interactively. This is useful for rapid iteration without restarting your MCP client.

If the status shows "Failed to connect" double-check that which api-test-mcp resolves and that pip install -e . completed without errors

Running Tests

Install test dependencies and run the suite:

# install test dependencies
pip install pytest pytest-asyncio respx

# run the whole test suite
pytest -v

All integration tests use respx to mock HTTP responses. No real network calls are made, so the suite runs fast and offline. The test suite also consisted of unit test and integration test

OpenCode Setup

Edit opencode.json (already configured at project root):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "api-test-mcp": {
      "type": "local",
      "command": ["api-test-mcp"],
      "enabled": true
    }
  }
}

Claude Desktop Setup

Edit claude_desktop_config.json (usually at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "api-test-mcp": {
      "command": "api-test-mcp"
    }
  }
}

Restart Claude Desktop after saving.

Usage

The test_api tool supports two modes:

cURL mode

Pass a raw cURL command, and then the server parses method, URL, headers, and payload automatically into restructured data. Example prompt that you might be used:

"Please test this API using this cURL: curl -X POST https://api.example.com/v1/users -H 'Authorization: Bearer xxx' -d '{"name":"test"}', ensure status code is 201 and response contains 'id'"

Structured mode

Provide individual fields rather than used a cURL command. Example prompt:

"Please test this API at https://api.example.com/v1/users with method GET, and the request header is {"Content-Type":"application/json"}, ensure status code is 200 and response body contains 'data'" attribute

Assertions

At the moment, this library provides built-in assertions that proved useful for testing the API, such as:

Parameter	Type	Description
required_status_code	int	Assert exact status code
required_status_code_range	str	Assert status code is within a range (e.g. "2xx", "200-299")
required_response_fields	list[str]	Assert fields exist in JSON response
required_response_contains	str	Assert response body contains a substring

Response

The tool returns a formatted console string with box-drawing, pass/fail symbols, and a summary:

Passing (with assertions)

┌──────────────────────────────────────────────┐
│ Api Test Result                              │
└──────────────────────────────────────────────┘

API Name        : create-user
Method          : POST
URL             : https://api.example.com/v1/users
Status Code     : 201
Response Time   : 142.35 ms
Overall Result  : Passed

Assertions
--------------------------------------------------
✓ status_code
✓ response_field_exist

Summary
--------------------------------------------------
Total Assertions : 2
Passed           : 2
Failed           : 0

Failing (assertion mismatch)

┌──────────────────────────────────────────────┐
│ Api Test Result                              │
└──────────────────────────────────────────────┘

API Name        : create-user
Method          : POST
URL             : https://api.example.com/v1/users
Status Code     : 500
Response Time   : 89.12 ms
Overall Result  : Failed

Assertions
--------------------------------------------------
✗ status_code

Summary
--------------------------------------------------
Total Assertions : 1
Passed           : 0
Failed           : 1

Network / runtime error

┌──────────────────────────────────────────────┐
│ Api Test Result                              │
└──────────────────────────────────────────────┘

API Name        : check-service
Method          : GET
URL             : https://api.internal.example.com/v1/status
Overall Result  : Failed

Error
--------------------------------------------------
ConnectError: [Errno 8] nodename nor servname provided, or not known

Logging

The server writes logs to log/mcp-api-test.log at the project root. Useful for debugging failed requests or tracing tool calls.

Environment Variables

The server loads a .env file via python-dotenv on startup. Useful for storing API keys, base URLs, etc. without hardcoding them in prompts.

Development

# Re-install after pulling changes
pip install -e .

# Run the MCP server directly
api-test-mcp

To run the test suite:

pip install -e ".[dev]"
pytest -v