# @topicforge/mcp

Official MCP server for [TopicForge](https://topicforge.net) — programmatic SEO batch jobs and growth tools.

[![npm version](https://img.shields.io/npm/v/@topicforge/mcp)](https://www.npmjs.com/package/@topicforge/mcp)
[![MCP Registry](https://img.shields.io/badge/MCP-net.topicforge%2Fmcp-blue)](https://registry.modelcontextprotocol.io/)
[![smithery badge](https://smithery.ai/badge/topicforge/topicforge-mcp)](https://smithery.ai/servers/topicforge/topicforge-mcp)

## Install

### npm (recommended)

```bash
npx -y @topicforge/mcp
```

Create an API key at [topicforge.net/app/settings/api-keys](https://topicforge.net/app/settings/api-keys).

### Claude Desktop / Cursor

```json
{
  "mcpServers": {
    "topicforge": {
      "command": "npx",
      "args": ["-y", "@topicforge/mcp"],
      "env": {
        "TOPICFORGE_API_KEY": "tf_live_..."
      }
    }
  }
}
```

### Claude Code

```bash
claude mcp add topicforge -e TOPICFORGE_API_KEY=tf_live_... -- npx -y @topicforge/mcp
```

One-click install buttons and more clients: [topicforge.net/developers](https://topicforge.net/developers?utm_source=github&utm_medium=mcp-readme)

## Environment

| Variable | Required | Description |
|----------|----------|-------------|
| `TOPICFORGE_API_KEY` | Yes | Workspace API key |
| `CONTENT_API_BASE_URI` | No | API base (default `https://api.topicforge.net`) |

## Tools

| Tool | Description |
|------|-------------|
| `topic_cluster` | Expand a seed topic into 15–25 article ideas |
| `faq_schema` | FAQ questions + FAQPage JSON-LD |
| `meta_description` | 150–160 char meta description |
| `run_batch` | Launch a credit-debited batch job (pay per article) |
| `get_batch_status` | Poll batch job progress |
| `get_article` | Fetch article by ID |
| `export_markdown` | Export article as markdown |
| `get_generation_settings` | Read workspace voice profile, product facts, and effective settings |
| `update_generation_settings` | Update workspace generation settings used by `run_batch` |

## Pricing

Pay per article — $10 single, volume packs from $3.99/article. [Pricing](https://topicforge.net/pricing?utm_source=github&utm_medium=mcp-readme)

## Development

This repo is a public mirror of the MCP package in the TopicForge monorepo. To build from source:

```bash
npm install
npm run build
npm start
```

Release tarball (fallback install):

```bash
npx -y https://topicforge.net/mcp/topicforge-mcp-1.0.0.tgz
```

## Links

- Smithery: https://smithery.ai/servers/topicforge/topicforge-mcp
- Developer docs: https://topicforge.net/developers
- MCP server card (tool metadata): https://topicforge.net/.well-known/mcp/server-card.json
- OpenAPI: https://topicforge.net/openapi.json
- MCP registry name: `net.topicforge/mcp`