Metadata-Version: 2.4
Name: certindex-mcp
Version: 0.1.0
Summary: MCP server exposing CertIndex's Certificate Transparency search tools to any MCP-compatible client.
Project-URL: Homepage, https://ctindex.io
Project-URL: Documentation, https://github.com/certindex/certindex-mcp#readme
Project-URL: Source, https://github.com/certindex/certindex-mcp
Project-URL: Issues, https://github.com/certindex/certindex-mcp/issues
Project-URL: Changelog, https://github.com/certindex/certindex-mcp/releases
Author-email: CertIndex contributors <support@ctindex.io>
License: MIT License
        
        Copyright (c) 2026 CertIndex contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agent,certificate-transparency,certificates,claude,ct-logs,llm,mcp,model-context-protocol,security,tls
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2.0
Requires-Dist: pydantic>=2.6
Provides-Extra: dev
Requires-Dist: pip-audit>=2.7; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# certindex-mcp

[![CI](https://github.com/certindex/certindex-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/certindex/certindex-mcp/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/certindex-mcp.svg)](https://pypi.org/project/certindex-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

An [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server
that exposes [CertIndex](https://ctindex.io)'s Certificate
Transparency search tools to any MCP-compatible client (Claude
Desktop, the MCP Inspector, Continue, etc.).

CertIndex indexes the full public CT corpus (~5 M certificates, growing
~100 k/day). This server wraps the public CertIndex REST API so an LLM
can ask questions like:

- "List every TLS certificate ever issued for `example.com`."
- "What subdomains has Let's Encrypt seen for `mycompany.io`?"
- "Show me certs expiring in the next 30 days for `api.mycompany.io`."
- "Pull the full PEM and CT log metadata for SHA-256 `<fingerprint>`."

## Why this repo exists

The CertIndex monorepo bundles an MCP server (mounted at
`https://api.ctindex.io/mcp`) that talks directly to the production
Postgres index. This standalone package is a thin **client-side**
shim: it speaks MCP to your editor / agent and forwards every tool
call to the hosted CertIndex REST API over HTTPS. Two consequences:

1. You don't need a copy of the index — sign up for a free API key
   at https://ctindex.io and you're done.
2. The package has a tiny dependency footprint (`mcp`, `httpx`,
   `pydantic`) — easy to audit, easy to vendor, no DB drivers.

## Install

```bash
pip install git+https://github.com/certindex/certindex-mcp
```

Or with [`uvx`](https://docs.astral.sh/uv/) for one-shot use:

```bash
uvx --from git+https://github.com/certindex/certindex-mcp certindex-mcp
```

(PyPI release coming soon — after that, plain `pip install certindex-mcp` /
`uvx certindex-mcp` will work too.)

## Quickstart — Claude Desktop

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

```json
{
  "mcpServers": {
    "certindex": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/certindex/certindex-mcp", "certindex-mcp"],
      "env": {
        "CERTINDEX_API_KEY": "ctx_live_..."
      }
    }
  }
}
```

Restart Claude Desktop. The six CertIndex tools (`search_certificates`,
`get_certificate`, `get_domain_certificates`, `get_subdomains`,
`get_latest_cert`, `get_expiring_certs`) appear in the tool tray.

## Quickstart — MCP Inspector

```bash
export CERTINDEX_API_KEY=ctx_live_...
npx @modelcontextprotocol/inspector uvx --from git+https://github.com/certindex/certindex-mcp certindex-mcp
```

## Configuration

| Env var | Default | Description |
| --- | --- | --- |
| `CERTINDEX_API_KEY` | *(required)* | Your CertIndex API key. Mint one at https://ctindex.io/app/keys |
| `CERTINDEX_BASE_URL` | `https://api.ctindex.io` | Override for self-hosted deployments / staging |
| `CERTINDEX_TIMEOUT` | `30` | Per-request HTTP timeout (seconds) |

## Security

Input validation, rate-limit handling, and our supply-chain posture are
documented in [SECURITY.md](SECURITY.md). Please report vulnerabilities
to security@ctindex.io rather than filing public issues.

## Development

```bash
git clone https://github.com/certindex/certindex-mcp
cd certindex-mcp
pip install -e ".[dev]"
pytest
```

CI runs on Python 3.11 / 3.12 / 3.13.

## License

[MIT](LICENSE) © CertIndex contributors.
