Metadata-Version: 2.4
Name: mcp-threads
Version: 0.1.0
Summary: MCP server wrapping the Threads API into 6 AI-callable tools for social media content management
Project-URL: Homepage, https://github.com/asgard-ai-platform/mcp-threads
Project-URL: Repository, https://github.com/asgard-ai-platform/mcp-threads
Project-URL: Issues, https://github.com/asgard-ai-platform/mcp-threads/issues
Author: asgard-ai-platform
License-Expression: MIT
License-File: LICENSE
Keywords: ai-agent,claude,mcp,social-media,threads
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.14
Requires-Dist: mcp[cli]>=1.27.1
Description-Content-Type: text/markdown

# MCP Threads

[![PyPI version](https://img.shields.io/pypi/v/mcp-threads)](https://pypi.org/project/mcp-threads/)
[![Python versions](https://img.shields.io/pypi/pyversions/mcp-threads)](https://pypi.org/project/mcp-threads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub stars](https://img.shields.io/github/stars/asgard-ai-platform/mcp-threads)](https://github.com/asgard-ai-platform/mcp-threads/stargazers)
[![GitHub issues](https://img.shields.io/github/issues/asgard-ai-platform/mcp-threads)](https://github.com/asgard-ai-platform/mcp-threads/issues)
[![GitHub last commit](https://img.shields.io/github/last-commit/asgard-ai-platform/mcp-threads)](https://github.com/asgard-ai-platform/mcp-threads/commits/main)
[![MCP](https://img.shields.io/badge/MCP-compatible-blue)](https://modelcontextprotocol.io/)

[繁體中文](README.zh-TW.md)

An open-source [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that wraps the [Threads API](https://developers.facebook.com/docs/threads) into 6 AI-callable tools for social media content management.

Built for [Claude Code](https://claude.ai/code), Claude Desktop, and any MCP-compatible AI client. Enables AI agents to read profiles, list posts/replies/mentions, check publishing limits, and publish text posts through natural language.

> **Disclaimer**: This project requires a valid Threads account token. It is intended for personal use and internal tooling only.

## What This Does

- **6 ready-to-use tools** covering profile, posts, replies, mentions, publishing limits, and text posting
- **MCP server** (stdio JSON-RPC 2.0) — plug into Claude Code and start interacting with Threads immediately
- **Minimal dependencies** — built on `mcp` SDK with no external API client libraries
- **Local stdio server** — works with Claude Desktop, Claude Code, and any MCP-compatible host

## Quick Start

### Install

```bash
pip install mcp-threads
```

Or use uvx (no install needed):

```bash
uvx mcp-threads serve
```

Set your token:

```bash
export THREADS_TOKEN="<your-token>"
```

### Use with Claude Code

Add the server via the Claude CLI:

```bash
claude mcp add --transport stdio threads -- mcp-threads serve
```

Or with the environment variable inline:

```bash
claude mcp add --transport stdio threads -e THREADS_TOKEN=your_token_here -- mcp-threads serve
```

If you clone the repo locally, the `.mcp.json` config will be auto-detected by Claude Code and all 6 tools become available immediately.

### Use with Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "threads": {
      "command": "mcp-threads",
      "args": ["serve"],
      "env": {
        "THREADS_TOKEN": "your_token_here"
      }
    }
  }
}
```

Or with uvx:

```json
{
  "mcpServers": {
    "threads": {
      "command": "uvx",
      "args": ["mcp-threads", "serve"],
      "env": {
        "THREADS_TOKEN": "your_token_here"
      }
    }
  }
}
```

## Tools (6)

| Tool | Description |
|------|-------------|
| `threads_profile_me` | Read the authenticated Threads user profile |
| `threads_posts_list` | List posts created by the authenticated user |
| `threads_publishing_limit` | Read publishing quota usage and config |
| `threads_mentions_list` | List public Threads posts that mention the authenticated user |
| `threads_replies_list` | List replies created by the authenticated user |
| `threads_post_text` | Create and publish a text post or reply |

## License

MIT
