Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@pyX-MCP Post a tweet saying 'Hello from pyX-MCP!'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
This is a Python client for integrating with the X (Twitter) API. You can operate the X API from AI assistants (such as Claude, Gemini, etc.) via MCP.
This library is a client for the X API. Although it also functions as an MCP server, the name x_client means it is a client for the X (Twitter) server.
graph TD
A["AI Agent<br>Claude / Gemini / Codex etc."] -->|MCP Protocol over stdio| B["MCP Server Entrypoint<br>(x_client.integrations.mcp_server)"]
%% Subgraph: Stabilize parsing by separating ID and display name
subgraph x_client_library["x_client Library — Single Python Process"]
B -->|Internal Call| C["XMCPAdapter"]
C -->|Internal Call| D["Service Layer<br>(PostService, MediaService)"]
D -->|Internal Call| E["Client Layer<br>(TweepyClient)"]
D -->|Internal Call| F["Client Layer<br>(OriginalClient ...future)"]
end
E -->|X API HTTP / REST| G["X Server<br>Twitter (X)"]
F -->|X API HTTP / REST| G["X Server<br>Twitter (X)"]
style B fill:#e1f5ff
style C fill:#e1f5ff
style D fill:#e1f5ff
style E fill:#e1f5ff
style F fill:#e1f5ff
style A fill:#fff4e6
style G fill:#f3e5f5
Clarification of Roles:
AI Agent (MCP Client): AI assistants like Claude Code, Claude Desktop, Gemini.
MCP Server: The MCP protocol-compatible server provided by this library.
X Client: The core function of this library. A client for the X API.
X Server: The main server of Twitter/X.
In other words, this library has two faces:
From the MCP perspective: It acts as an MCP server providing tools to AI agents.
From the X API perspective: It acts as an X API client communicating with the X server.
It is also possible to use the X API as a library without MCP (see bottom of README.md).
Related MCP server: Twitter MCP Server
Python 3.11 or higher
X (Twitter) developer account and a set of API keys
Package management tool uv (recommended)
You can operate the X API from AI assistants (such as Claude Code, Claude Desktop, codex-cli, Gemini, etc.).
By using uvx in all environments, you can get automatic dependency management and always stay up-to-date.
Describe the following in the MCP configuration file of each AI tool:
TOML format (Codex-CLI, etc.):
Published on PyPI
[mcp.servers.x_client]
command = "uvx"
args = ["--from", "pyx-mcp", "x-mcp-server"]
[mcp.servers.x_client.env]
X_API_KEY = "your-api-key"
X_API_SECRET = "your-api-secret"
X_ACCESS_TOKEN = "your-access-token"
X_ACCESS_TOKEN_SECRET = "your-access-token-secret"Latest from GitHub
[mcp.servers.x_client]
command = "uvx"
args = ["--from", "git+https://github.com/hellocybernetics/pyX-MCP", "x-mcp-server"]
[mcp.servers.x_client.env]
X_API_KEY = "your-api-key"
X_API_SECRET = "your-api-secret"
X_ACCESS_TOKEN = "your-access-token"
X_ACCESS_TOKEN_SECRET = "your-access-token-secret"JSON format (Claude Code, Gemini CLI, etc.):
Published on PyPI
{
"mcpServers": {
"x_client": {
"command": "uvx",
"args": ["--from", "pyx-mcp", "x-mcp-server"],
"env": {
"X_API_KEY": "your-api-key",
"X_API_SECRET": "your-api-secret",
"X_ACCESS_TOKEN": "your-access-token",
"X_ACCESS_TOKEN_SECRET": "your-access-token-secret"
}
}
}
}Latest from GitHub
{
"mcpServers": {
"x_client": {
"command": "uvx",
"args": ["--from", "git+https://github.com/hellocybernetics/pyX-MCP", "x-mcp-server"],
"env": {
"X_API_KEY": "your-api-key",
"X_API_SECRET": "your-api-secret",
"X_ACCESS_TOKEN": "your-access-token",
"X_ACCESS_TOKEN_SECRET": "your-access-token-secret"
}
}
}
}Important: Please restart your AI tool completely after setting it up.
Ask your AI assistant as follows:
"List the available X API tools"or
"Post 'Hello from MCP!'"✅ Environment Independent: No Node.js required, works only with a Python environment
✅ Automatic Dependency Management: uv automatically builds and caches virtual environments
✅ Always Up-to-date: --from pyx-mcp automatically gets the latest version from PyPI
✅ Unified Configuration: Same configuration method for all AI assistants
The following tools are available via MCP:
create_post: Text posts, posts with images/videos, replies, quote posts
delete_post: Delete a post
get_post: Get a post by its ID
create_thread: Automatically split long text into a thread post
repost_post: Repost a post
undo_repost: Undo a repost
search_recent_posts: Search for posts from the last 7 days (with author information)
upload_image: Upload an image (JPEG/PNG/WebP/GIF, max 5MB)
upload_video: Upload a video (MP4, max 512MB, chunked upload supported)
get_auth_status: Get authentication status and rate limit information
You: "Post 'Hello from Claude via MCP!'"
Claude: Using the create_post tool...
Post completed! Post ID: 1234567890You: "Search for recent posts about 'MCP protocol'"
Claude: Using the search_recent_posts tool...
Found 3 posts:
1. @user1: I tried using MCP...
2. @user2: Model Context Protocol is...AI Assistant ↔ MCP Server (stdio) ↔ XMCPAdapter ↔ Service Layer ↔ X APIConfigurationError: Missing authentication information. Check .env and environment variables.
AuthenticationError: Token expired. Re-run the OAuth flow.
RateLimitExceeded: Rate limit reached. Back off with reference to reset_at.
MediaProcessingTimeout/Failed: Timed out waiting for video processing to complete. Adjust timeout and video quality.
Missing credentials: Check environment variables with echo $X_API_KEY. Check if .env is saved with 0o600.
Invalid token: Re-run the OAuth flow to update authentication information.
Video timeout: Extend the timeout of upload_video or re-encode with ffmpeg.
It can also be called directly from Python code.
uv add pyx-mcpTo use this library, you need to get the following four pieces of authentication information from your X (Twitter) developer account.
Access the X Developer Portal:
Go to https://developer.x.com/en/portal/dashboard and log in.
Select or create an application:
Select an existing application or create a new one.
Check keys and tokens:
On the application dashboard, go to the "Keys and Tokens" tab.
Generate and set permissions:
API Key and Secret: Check or regenerate in the "Consumer Keys" section.
Access Token and Secret: In the "Authentication Tokens" section, generate an access token and secret with Read and Write permissions.
Set these retrieved values in the environment variables or .env file described below.
Set the authentication information with environment variables or an .env file:
export X_API_KEY="your_api_key"
export X_API_SECRET="your_api_secret"
export X_ACCESS_TOKEN="your_access_token"
export X_ACCESS_TOKEN_SECRET="your_access_token_secret"
export X_BEARER_TOKEN="your_bearer_token" # for v2 API (optional)Or in an .env file (placed in the project root):
X_API_KEY=your_api_key
X_API_SECRET=your_api_secret
X_ACCESS_TOKEN=your_access_token
X_ACCESS_TOKEN_SECRET=your_access_token_secret
X_BEARER_TOKEN=your_bearer_token.env is automatically set to 0o600 (owner read/write only). .env* is .gitignored.
from x_client.config import ConfigManager
from x_client.factory import XClientFactory
from x_client.services.post_service import PostService
from x_client.services.media_service import MediaService
# 1. Load authentication information
config = ConfigManager()
client = XClientFactory.create_from_config(config)
# 2. Initialize the service layer
post_service = PostService(client)
media_service = MediaService(client)
# 3. Create a post
post = post_service.create_post(text="Hello from x_client!")
print(f"Post created: {post.id}")
# 4. Post with an image
from pathlib import Path
media_result = media_service.upload_image(Path("image.png"))
post = post_service.create_post(
text="Check out this image!",
media_ids=[media_result.media_id]
)
# 5. Post a long thread
thread = post_service.create_thread(
'''Python 3.11 highlights... (long text)''',
chunk_limit=200,
)
for idx, segment_post in enumerate(thread.posts, start=1):
print(f"Segment {idx}: {segment_post.id}")
if not thread.succeeded:
print("Thread failed", thread.error)
# 6. Repost operation
repost_state = post_service.repost_post(post.id)
print("Reposted:", repost_state.reposted)
undo_state = post_service.undo_repost(post.id)
print("Repost removed:", not undo_state.reposted)
# 7. Search with author information
search_results = post_service.search_recent(
"from:twitterdev",
expansions=["author_id"],
user_fields=["username", "verified"],
post_fields=["created_at"],
)
for item in search_results:
author = item.author.username if item.author else "unknown"
print(author, item.text)It can also be called directly from other than MCP clients:
from x_client.integrations.mcp_adapter import XMCPAdapter
adapter = XMCPAdapter() # Authentication information is automatically loaded by ConfigManager
post = adapter.create_post({"text": "Hello from MCP!"})
print(post)
media = adapter.upload_image({"path": "/path/to/image.png"})
adapter.create_post({"text": "Image post", "media_ids": [media["media_id"]]})PostService has structured logging and event hooks built in:
import logging
from x_client.config import ConfigManager
from x_client.factory import XClientFactory
from x_client.services.post_service import PostService
logging.basicConfig(level=logging.INFO)
client = XClientFactory.create_from_config(ConfigManager())
def metrics_hook(event: str, payload: dict[str, object]) -> None:
# Integration point for Prometheus / OpenTelemetry, etc.
print("metrics", event, payload)
post_service = PostService(client, event_hook=metrics_hook)
post_service.create_post("observability ready!")The event hook consolidates both success and failure into a single callback, making it easy to send metrics and integrate with distributed tracing.
uv syncThis will create the x-mcp-server command in .venv/bin/.
To run the MCP server under development directly:
{
"mcpServers": {
"x-client": {
"command": "/absolute/path/to/twitter/.venv/bin/x-mcp-server",
"env": {
"X_API_KEY": "your-api-key",
"X_API_SECRET": "your-api-secret",
"X_ACCESS_TOKEN": "your-access-token",
"X_ACCESS_TOKEN_SECRET": "your-access-token-secret"
}
}
}
}Method 2: Direct use of uv
{
"mcpServers": {
"x-client": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/twitter", "python", "-m", "x_client.integrations.mcp_server"],
"env": {
"X_API_KEY": "your-api-key",
"X_API_SECRET": "your-api-secret",
"X_ACCESS_TOKEN": "your-access-token",
"X_ACCESS_TOKEN_SECRET": "your-access-token-secret"
}
}
}
}Method 3: Launcher script
{
"mcpServers": {
"x-client": {
"command": "/absolute/path/to/twitter/scripts/run_mcp_server.sh",
"env": { "X_API_KEY": "...", "X_API_SECRET": "...", "X_ACCESS_TOKEN": "...", "X_ACCESS_TOKEN_SECRET": "..." }
}
}
}Important: Replace /absolute/path/to/twitter with the actual project path.
You can easily post from the command line using examples/create_post.py.
# Text only
python examples/create_post.py "Hello from x_client!"
# With image
python examples/create_post.py "Check out this image!" --image path/to/image.png
# With video (max 512MB, chunked upload supported)
python examples/create_post.py "Check out this video!" --video path/to/video.mp4
# Use .env from a different path
python examples/create_post.py "Hello with custom env" --dotenv /secure/path/.env# Long thread post (auto-split with chunk_limit=180)
python examples/create_post.py "Long form update..." --thread --chunk-limit 180
# Post a thread from a file (assuming UTF-8 text)
python examples/create_post.py --thread-file docs/thread_draft.txt
# Example of a long Japanese thread (break lines appropriately under 280 characters)
python examples/create_post.py --thread-file examples/long_thread_ja.txt --chunk-limit 180
# Example of a long English thread (maintaining sentence breaks)
python examples/create_post.py --thread-file examples/long_thread_en.txt --chunk-limit 240
# Wait 8 seconds between each post to avoid rate limits
python examples/create_post.py --thread-file examples/long_thread_en.txt --segment-pause 8
# Choose a split strategy (simple | sentence | paragraph)
python examples/create_post.py --thread-file examples/long_thread_en.txt \
--chunk-limit 240 --split-strategy sentence# Delete the first tweet of a failed thread (used to resolve duplicate errors)
python examples/create_post.py --delete 1234567890123456789
# Repost / Undo repost
python examples/create_post.py --repost 1234567890
python examples/create_post.py --undo-repost 1234567890Japanese: If there are many full-width characters, filling up to the 280-character limit can make it difficult to read, so keep --chunk-limit to around 150-200 characters to maintain chunks for each phrase. Also, since splitting immediately after a punctuation mark can break the context, it is safe to insert a blank line for each paragraph on the text file side.
English: When including URLs or emojis, Twitter counts them as 23 characters, so set --chunk-limit with a margin. If you add a line break for each sentence, it will be easier to read after splitting.
When re-posting a thread, if you post the exact same body text within 24 hours, you will get a Duplicate content error due to X's specifications. Please delete the previously posted thread or add a unique phrase such as a timestamp to the text.
The X API may return HTTP 429 (Too Many Requests) if you post continuously in a short period of time. This library detects RateLimitExceeded and waits according to x-rate-limit-reset in the response header before retrying, but if a 429 occurs, please wait 2-3 minutes before re-executing the command. Setting --segment-pause to about 5–10 seconds makes it easier to avoid 429 in advance.
# Test MCP server operation
uv run python scripts/test_mcp_server.py
# Unit tests
uv run pytest tests/unit/test_mcp_adapter.py -v
# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=x_client --cov-report=html
# Verbose mode
uv run pytest -v
# Specific test file
uv run pytest tests/unit/test_tweepy_client.pyDual client configuration: tweepy.Client (v2) for posts, tweepy.API (v1.1) for media
Secure authentication information management using .env and OAuth flow integration
High-level API with PostService / MediaService
Long thread posting utility and automatic reply chain construction
Repost/undo API and MCP tools
Support for specifying expansions/fields in the search API and resolving author information
Structured logging and event hooks built into the service layer
Operation from AI assistants via MCP (Model Context Protocol) integration
Please report bugs and suggestions for improvement via issues or pull requests. For details on project policies and design, please refer to docs/ and add comments as necessary.
Post a new post with optional media, reply, or quote
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Text content of the post (max 280 characters) | |
| media_ids | No | List of media IDs to attach (max 4) | |
| in_reply_to | No | Post ID to reply to | |
| quote_post_id | No | Post ID to quote | |
| reply_settings | No | Who can reply to this post |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description should carry full burden. It only states the action without disclosing behavioral traits such as authentication requirements, rate limits, or success/failure outcomes.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Extremely concise single sentence, front-loaded with key information. Every word contributes to understanding the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 5 parameters (1 required), no output schema, and no annotations, the description is insufficient. It does not explain return value, error cases, or contextual relationships with siblings like delete_post or get_post.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so description adds minimal extra meaning. It mentions optional media, reply, or quote which maps to parameters, but no further constraints or behavioral details beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb 'Post', resource 'new post', and optional features like media, reply, or quote. Distinct from siblings such as create_thread and repost_post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implied usage for creating a single post, but no explicit guidance on when to use versus alternatives like create_thread. No exclusions or when-not scenarios mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a multi-post thread from long text
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | Full text content that will be split into a thread | |
| chunk_limit | No | Maximum characters per post segment | |
| in_reply_to | No | Post ID to reply to with the first segment | |
| split_strategy | No | Optional split strategy. 'simple' (default) splits by whitespace; 'sentence' keeps sentences together; 'paragraph' respects blank lines. | |
| rollback_on_failure | No | Whether to delete previously created posts if a later segment fails |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It fails to disclose key behavioral traits such as that the text is split into multiple posts, that failures may trigger rollback, or any authentication or rate-limit implications. The description is too vague.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently states the core purpose, but it is overly brief and omits important context and usage details, reducing its overall utility.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 5 parameters, no output schema, and multiple sibling tools, the description is incomplete. It fails to explain the splitting mechanism, the structure of the resulting thread, or how parameters affect behavior, leaving significant gaps for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter already having a detailed description. The tool description adds no additional meaning beyond the schema, so a baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Create' and resource 'multi-post thread from long text', distinguishing it from sibling 'create_post' which presumably creates a single post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not explicitly state when to use this tool versus alternatives like 'create_post'. While the name and description imply it is for long text that needs splitting, no guidance on exclusion or context is provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a post by ID
| Name | Required | Description | Default |
|---|---|---|---|
| post_id | Yes | ID of the post to delete |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description only states 'delete' which implies mutation, but no details on side effects, permissions, or error conditions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single, clear sentence with no unnecessary words. Appropriate for a simple tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a straightforward delete operation with one parameter. Lacks mention of return value or confirmation, but is minimally sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers the only parameter (post_id) with description. Description adds no extra semantic value beyond schema. Baseline 3 due to 100% coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action (delete) and resource (post) with identifier (by ID). It distinguishes from sibling tools like create_post and get_post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives (e.g., undo_repost). Lacks context about irreversible action or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get authentication status and rate limit information
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description only states the outputs. It does not disclose behavioral aspects like whether authentication is required, if the call is read-only, or rate limit implications.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, no extraneous content, and directly communicates the purpose. Perfectly concise for a simple status-check tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and zero parameters, the description is largely complete. It could mention the structure of auth status (e.g., user info), but for a status-check tool, it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the schema coverage is 100% (trivially). The description adds value beyond the schema by specifying 'rate limit information' as an additional output.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states two specific outputs: authentication status and rate limit information. The name 'get_auth_status' aligns well, and there is no confusion with sibling tools (all post-related).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool vs alternatives is provided. However, since no sibling tools serve a similar purpose, the omission is less critical, but still lacks context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve a specific post by ID
| Name | Required | Description | Default |
|---|---|---|---|
| post_id | Yes | ID of the post to retrieve |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations and minimal description: does not disclose behavioral traits such as required authentication, error handling for missing posts, or rate limits; for a read operation, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no wasted words; efficient and front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple one-parameter retrieval with no output schema, the description is minimally adequate but lacks information about return value or error scenarios.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the description adds no additional meaning beyond the schema's parameter description; baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states 'Retrieve a specific post by ID' with a specific verb and resource, distinguishing it from sibling tools like create_post or delete_post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus alternatives; usage is implied as a simple retrieval, but no when-not or exclusions are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Repost a post by ID
| Name | Required | Description | Default |
|---|---|---|---|
| post_id | Yes | ID of the post to repost |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden for behavioral disclosure. It only states 'Repost a post by ID' without detailing side effects (e.g., notifications, permissions, whether the original post is affected). This is insufficient for a mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, front-loaded sentence with no wasted words. However, it could be expanded to include more useful information without becoming verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the single parameter, no output schema, and no annotations, the description lacks details on return values, expected outcomes, and prerequisites. It is not sufficiently complete for an agent to fully understand the tool's behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so baseline is 3. The description 'ID of the post to repost' adds minimal meaning beyond the parameter name; it does not specify format or source of the ID.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (repost) and resource (post) and that it uses an ID. However, it does not differentiate from sibling tools like 'undo_repost' or 'create_post' by explaining what reposting entails (e.g., creating a copy or resharing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives such as 'create_post' or 'undo_repost'. There is no mention of context or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search for recent posts (past 7 days)
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Search query using X search syntax | |
| expansions | No | List of expansions to request (e.g., author_id) | |
| max_results | No | Maximum number of posts to return | |
| user_fields | No | User fields to request when expansions include author | |
| tweet_fields | No | Additional tweet fields to request |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description implies a read operation but does not disclose behavioral traits like rate limits, data freshness, or that it returns a list of posts. Minimal transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no fluff. Efficient but could be slightly more detailed without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, no output schema, and no annotations, the description provides minimal context (only 7 days constraint). Lacks explanation of search behavior or return value, making it incomplete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with descriptions for each parameter. Description adds no extra meaning beyond the schema, so baseline score is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Search', resource 'posts', and a time constraint 'past 7 days'. It is specific but does not differentiate from siblings like get_post or mention search syntax.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool vs alternatives (e.g., get_post for a specific post). The description lacks any 'when' or 'when-not' context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Undo an existing repost by ID
| Name | Required | Description | Default |
|---|---|---|---|
| post_id | Yes | ID of the post to undo repost |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, and description only states the action. Lacks disclosure of side effects, permissions, or return behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with no extraneous information. Highly concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a simple tool with one parameter and no output schema, but lacks detail on what 'undo' entails.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% for the single parameter. Description adds no additional meaning beyond the schema, so baseline score applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states verb (undo), resource (repost), and identifier (by ID). Distinguishes from siblings like repost_post and delete_post.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no prerequisites, no exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload an image file (max 5MB, JPEG/PNG/WebP/GIF). Please provide an absolute file path.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the image file | |
| media_category | No | Media category (post_image or post_gif) | post_image |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses file size and format constraints but does not mention success/failure responses, authentication requirements, or any side effects (e.g., overwriting existing files).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise with two sentences, no fluff, and front-loads the essential information immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that there is no output schema, the description should explain what the tool returns upon success (e.g., an image ID or URL). It also omits prerequisites like authentication. The file constraints are covered, but the output behavior is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already describes both parameters (100% coverage). The description adds value by reiterating the absolute path requirement and adding file size/format constraints not in the schema. However, it does not elaborate on the 'media_category' parameter's purpose or options beyond the default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('upload'), the resource ('image file'), and includes constraints (max 5MB, allowed formats JPEG/PNG/WebP/GIF). It implicitly distinguishes from sibling 'upload_video' by specifying 'image file'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description tells the user to provide an absolute file path and lists file size/format restrictions, but does not explicitly state when not to use this tool (e.g., for non-image files) or mention alternatives like 'upload_video'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Upload a video file (max 512MB, MP4 with H.264/AAC). Please provide an absolute file path.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Absolute path to the video file | |
| timeout | No | Maximum time in seconds to wait for processing completion | |
| poll_interval | No | Interval in seconds to check processing status | |
| media_category | No | Media category (post_video) | post_video |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description adds constraints (size, format) but lacks disclosure of processing behavior, rate limits, or authentication needs. It does not mention that the timeout and poll_interval parameters suggest asynchronous processing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no unnecessary words, front-loading key constraints (size, format, absolute path).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description fails to explain return values, error handling, or the significance of timeout/poll_interval parameters. It is not fully complete for an upload tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% so baseline is 3. The description adds value by emphasizing the path must be absolute, but does not elaborate on timeout or poll_interval beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool uploads a video file with specific constraints (max size, format) and requires an absolute path. It effectively distinguishes from siblings like upload_image.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for video uploads but does not explicitly state when to use vs alternatives like upload_image, nor does it mention when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.4create_postcreate_threaddelete_postget_auth_statusget_postrepost_postsearch_recent_postsundo_repostupload_imageupload_videoAll tools have clearly distinct purposes: create, delete, get, repost, undo repost, search, auth status, and two media uploads differentiated by type/size. No overlap or ambiguity.
All tool names follow a consistent verb_noun pattern in snake_case (e.g., create_post, delete_post, upload_image). Even 'undo_repost' and 'get_auth_status' fit the pattern well.
With 10 tools covering posting, reading, searching, media uploads, reposts, and auth status, the count is well-scoped for a social media client. No unnecessary or missing tools.
Core operations are covered (CRUD for posts, search, media upload, repost). Missing edit post and timeline listing are minor gaps that agents can work around.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
X (formerly Twitter) posts, profiles, and search for AI agents. Free key, self-minted, no signup.
Search, label, and manage your X (Twitter) bookmarks from any MCP client via Tweetsmash
Connect any AI agent to 11+ social platforms: schedule, publish & track posts via hosted MCP.
Twitter/X read-only MCP server — 12 tools: search, users, tweets, followers, timelines, trends.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/hellocybernetics/pyX-MCP'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
