Metadata-Version: 2.5
Name: machina-mcp
Version: 0.1.1
Summary: MCP server for Machina — x402-powered AI agent services (URL extraction, PDF processing, code scanning, email validation, domain intelligence)
Project-URL: Homepage, https://mach402.dev
Project-URL: Documentation, https://mach402.dev/docs/buyer-guide
Project-URL: Repository, https://github.com/NyTerry/machina-mcp
Project-URL: Bug Tracker, https://github.com/NyTerry/machina-mcp/issues
Author-email: Machina <hello@mach402.dev>
License: MIT
License-File: LICENSE
Keywords: agent-services,ai-agent,code-scanner,email-validation,machina,mcp,model-context-protocol,pdf,url-extraction,x402
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Requires-Dist: httpx>=0.24.0
Requires-Dist: mcp>=2.0.0
Requires-Dist: x402[evm]>=2.0.0
Description-Content-Type: text/markdown

# machina-mcp

**Machina as an MCP server.** Use Machina's x402-powered agent services directly from Claude Desktop, Cursor, or any MCP-compatible AI host — no x402 integration required.

Payments happen automatically on every tool call. Configure once, pay per use.

## Tools

| Tool | What it does | Cost |
|---|---|---|
| `url_extract` | Fetch any URL → clean Markdown | $0.005 |
| `scan_python` | Scan Python code for security vulnerabilities | $0.020 |
| `validate_email` | Validate a single email (syntax, MX, SMTP) | $0.007 |
| `validate_email_bulk` | Validate up to 100 emails | $0.500 |
| `domain_intel` | DNS, WHOIS, SSL, tech stack for a domain | $0.050 |
| `pdf_inspect` | PDF page count + metadata | **FREE** |
| `pdf_extract` | PDF → Markdown (≤50 pages) | $0.050 |
| `pdf_extract_large` | PDF → Markdown (≤200 pages) | $0.180 |

Payments are in USDC on [Base](https://base.org) (Coinbase's L2). Gas fees are fractions of a cent.

---

## Quick Start

### 1. Install

```bash
pip install machina-mcp
```

### 2. Get a wallet + fund it

You need an Ethereum wallet with a small USDC balance on Base mainnet.

**Option A — New wallet (easiest):**
```bash
python -c "from eth_account import Account; a = Account.create(); print('Address:', a.address); print('Key:', a.key.hex())"
```
Copy the address and send it $1–5 USDC on Base via [Coinbase](https://coinbase.com) or [bridge.base.org](https://bridge.base.org).

**Option B — Existing wallet:**
Export your private key from MetaMask: Account Details → Export Private Key.

### 3. Set your key

```bash
export MACHINA_WALLET_KEY=0xYOUR_PRIVATE_KEY
```

### 4. Add to Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "machina": {
      "command": "machina-mcp",
      "env": {
        "MACHINA_WALLET_KEY": "0xYOUR_PRIVATE_KEY"
      }
    }
  }
}
```

Restart Claude Desktop. The 8 Machina tools will appear automatically.

---

## Usage Examples

Once connected, ask Claude:

- *"Extract the content from https://example.com"* → uses `url_extract`
- *"Scan this Python code for security issues: [paste code]"* → uses `scan_python`
- *"Check if john@example.com is a real email"* → uses `validate_email`
- *"Get DNS and WHOIS info for openai.com"* → uses `domain_intel`
- *"How many pages is this PDF?"* → uses `pdf_inspect` (free)
- *"Extract text from report.pdf"* → uses `pdf_extract`

---

## Configuration

| Env var | Required | Default | Description |
|---|---|---|---|
| `MACHINA_WALLET_KEY` | ✅ | — | Ethereum private key (hex, 0x-prefixed) |
| `MACHINA_NETWORK` | ❌ | `eip155:8453` | CAIP-2 network ID (Base mainnet) |
| `MACHINA_BASE_URL` | ❌ | `https://mach402.dev` | Machina API base URL |

**Testnet mode** (free, mock payments):
```bash
export MACHINA_NETWORK=eip155:84532
export MACHINA_BASE_URL=https://mach402.dev  # testnet endpoints at same URL when TESTNET_MODE=true
```

---

## How payments work

1. Your agent calls a Machina MCP tool (e.g. `url_extract`)
2. The MCP server sends the request to `mach402.dev`
3. Machina responds with a 402 Payment Required + exact USDC amount
4. The MCP server signs and sends the x402 payment automatically using your wallet key
5. Machina verifies payment on-chain and returns the result
6. The result is passed back to your agent

The agent never sees any of this — it just calls a tool and gets a result.

---

## Running standalone (for testing)

```bash
# Test with MCP Inspector
npx @modelcontextprotocol/inspector machina-mcp

# Or run directly
export MACHINA_WALLET_KEY=0x...
machina-mcp
```

---

## Pricing

Machina charges per call in USDC on Base mainnet. Payments are settled on-chain via [Coinbase CDP](https://docs.cdp.coinbase.com/x402/). There are no subscriptions, no minimums, no monthly fees.

A $5 USDC balance covers ~1,000 URL extractions or ~250 Python code scans.

---

## Links

- **API docs:** https://mach402.dev/docs
- **Buyer guide:** https://mach402.dev/docs/buyer-guide
- **Source:** https://github.com/NyTerry/machina-mcp
- **Issues:** https://github.com/NyTerry/machina-mcp/issues

---

## License

MIT

<!-- mcp-name: io.github.NyTerry/machina-mcp -->
