{"_id":"agent-twitter-client-mcp","name":"agent-twitter-client-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"agent-twitter-client-mcp","version":"0.1.0","description":"MCP server for Twitter integration using agent-twitter-client","main":"build/index.js","type":"module","scripts":{"build":"tsc","start":"node build/index.js","dev":"tsx src/index.ts","test":"jest","test:interface":"tsx src/test-interface.ts","lint":"eslint src/**/*.ts","prepare":"npm run build","prepublishOnly":"npm run lint && npm test","version":"npm run lint && git add -A src","postversion":"git push && git push --tags"},"bin":{"agent-twitter-client-mcp":"build/index.js","agent-twitter-client-mcp-test":"build/test-interface.js"},"keywords":["twitter","mcp","model-context-protocol","agent","ai","agent-twitter-client","claude","anthropic","grok"],"author":{"name":"ryanmac"},"license":"MIT","dependencies":{"@modelcontextprotocol/sdk":"^0.6.0","agent-twitter-client":"^0.0.18","dotenv":"^16.4.7","winston":"^3.11.0","zod":"^3.24.2"},"devDependencies":{"@types/jest":"^29.5.11","@types/node":"^20.11.24","@typescript-eslint/eslint-plugin":"^7.0.1","@typescript-eslint/parser":"^7.0.1","eslint":"^8.56.0","jest":"^29.7.0","ts-jest":"^29.1.1","tsx":"^4.7.1","typescript":"^5.3.3"},"engines":{"node":">=18.0.0"},"repository":{"type":"git","url":"git+https://github.com/ryanmac/agent-twitter-client-mcp.git"},"bugs":{"url":"https://github.com/ryanmac/agent-twitter-client-mcp/issues"},"homepage":"https://github.com/ryanmac/agent-twitter-client-mcp#readme","publishConfig":{"access":"public"},"_id":"agent-twitter-client-mcp@0.1.0","gitHead":"a500bb4a9cceda6c461155cbbfb1965dc2909397","types":"./build/index.d.ts","_nodeVersion":"20.18.3","_npmVersion":"10.8.2","dist":{"integrity":"sha512-q90AfOYzFGna/Q9XjQuC0RpF0z2uCToQvXp/PDmuqlPnFjbVIFnQlLgiHqWLES+j1t6GCpPGMPpcQ5i9YB/pWA==","shasum":"255d5f11d1f74f0d202b6edb7a3bc19603294176","tarball":"https://registry.npmjs.org/agent-twitter-client-mcp/-/agent-twitter-client-mcp-0.1.0.tgz","fileCount":45,"unpackedSize":199862,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCHJLnnT14lzX+WFHtP0okH1PgeqzX7iZNAR8ELjyMNdwIgc1Gzli3y/5frMPHV0zRYO5Zedey1sccGv06B/vCKWm0="}]},"_npmUser":{"name":"ryanmac-npm","email":"ryan.maccarthy@gmail.com"},"directories":{},"maintainers":[{"name":"ryanmac-npm","email":"ryan.maccarthy@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/agent-twitter-client-mcp_0.1.0_1741460771649_0.2843944675892238"},"_hasShrinkwrap":false}},"time":{"created":"2025-03-08T19:06:11.545Z","0.1.0":"2025-03-08T19:06:11.839Z","modified":"2025-03-08T19:06:12.113Z"},"maintainers":[{"name":"ryanmac-npm","email":"ryan.maccarthy@gmail.com"}],"description":"MCP server for Twitter integration using agent-twitter-client","homepage":"https://github.com/ryanmac/agent-twitter-client-mcp#readme","keywords":["twitter","mcp","model-context-protocol","agent","ai","agent-twitter-client","claude","anthropic","grok"],"repository":{"type":"git","url":"git+https://github.com/ryanmac/agent-twitter-client-mcp.git"},"author":{"name":"ryanmac"},"bugs":{"url":"https://github.com/ryanmac/agent-twitter-client-mcp/issues"},"license":"MIT","readme":"# agent-twitter-client-mcp\n\n[![npm version](https://img.shields.io/npm/v/agent-twitter-client-mcp.svg)](https://www.npmjs.com/package/agent-twitter-client-mcp)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js Version](https://img.shields.io/node/v/agent-twitter-client-mcp.svg)](https://nodejs.org)\n\nA Model Context Protocol (MCP) server that integrates with Twitter using the `agent-twitter-client` package, allowing AI models to interact with Twitter without direct API access.\n\n## Features\n\n- **Authentication Options**:\n\n  - Cookie-based authentication (recommended)\n  - Username/password authentication\n  - Twitter API v2 credentials\n\n- **Tweet Operations**:\n\n  - Fetch tweets from users\n  - Get specific tweets by ID\n  - Search tweets\n  - Send tweets with text and media\n  - Create polls\n  - Like, retweet, and quote tweets\n\n- **User Operations**:\n\n  - Get user profiles\n  - Follow users\n  - Get followers and following lists\n\n- **Grok Integration**:\n  - Chat with Grok via Twitter's interface\n  - Continue conversations with conversation IDs\n  - Get web search results and citations\n  - Access Twitter's real-time data through Grok\n  - **Note**: Grok functionality requires [agent-twitter-client v0.0.19](https://github.com/elizaOS/agent-twitter-client/releases/tag/0.0.19) or higher\n\n## Documentation\n\n- [Developer Guide](docs/DEVELOPER_GUIDE.md) - Comprehensive guide for developers\n- [Testing Guide](docs/TESTING.md) - Instructions for testing the MCP\n- [Agent Guide](docs/AGENT_GUIDE.md) - Guide for AI agents on how to use the Twitter MCP\n- [Contributing Guide](CONTRIBUTING.md) - Guidelines for contributing to this project\n- [Changelog](CHANGELOG.md) - History of changes to this project\n\n## Quick Start\n\n### Installation\n\n```bash\n# Install globally\nnpm install -g agent-twitter-client-mcp\n\n# Or install locally\nnpm install agent-twitter-client-mcp\n```\n\n### Basic Usage\n\n1. Create a `.env` file with your Twitter credentials (see [Authentication Methods](#authentication-methods))\n2. Run the MCP server:\n\n```bash\n# If installed globally\nagent-twitter-client-mcp\n\n# If installed locally\nnpx agent-twitter-client-mcp\n```\n\n### Port Configuration\n\nBy default, the MCP server runs on port 3000. If you need to change this (for example, if you already have an application running on port 3000), you have several options:\n\n#### Option 1: Using Environment Variables\n\nSet the `PORT` environment variable:\n\n```bash\nPORT=3001 npx agent-twitter-client-mcp\n```\n\n#### Option 2: Using Docker Compose\n\nIf using Docker Compose, you can configure both the host and container ports in your `.env` file:\n\n```\n# .env file\nMCP_HOST_PORT=3001    # The port on your host machine\nMCP_CONTAINER_PORT=3000  # The port inside the container\n```\n\nThen run:\n\n```bash\ndocker-compose up -d\n```\n\nThis will map port 3001 on your host to port 3000 in the container, allowing you to access the MCP at http://localhost:3001 while your other application continues to use port 3000.\n\n### Setup with Claude Desktop\n\n1. Configure Claude Desktop to use this MCP by adding to your config file:\n\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-twitter-client-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"agent-twitter-client-mcp\"],\n      \"env\": {\n        \"AUTH_METHOD\": \"cookies\",\n        \"TWITTER_COOKIES\": \"[\\\"auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com\\\", \\\"ct0=YOUR_CT0_VALUE; Domain=.twitter.com\\\", \\\"twid=u%3DYOUR_USER_ID; Domain=.twitter.com\\\"]\"\n      }\n    }\n  }\n}\n```\n\n2. Restart Claude Desktop\n\n### Authentication Methods\n\n#### Cookie Authentication (Recommended)\n\n```json\n{\n  \"AUTH_METHOD\": \"cookies\",\n  \"TWITTER_COOKIES\": \"[\\\"auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com\\\", \\\"ct0=YOUR_CT0_VALUE; Domain=.twitter.com\\\", \\\"twid=u%3DYOUR_USER_ID; Domain=.twitter.com\\\"]\"\n}\n```\n\nTo obtain cookies:\n\n1. Log in to Twitter in your browser\n2. Open Developer Tools (F12)\n3. Go to the Application tab > Cookies\n4. Copy the values of `auth_token`, `ct0`, and `twid` cookies\n5. Make sure to include the `Domain=.twitter.com` part for each cookie\n\n#### Username/Password Authentication\n\n```json\n{\n  \"AUTH_METHOD\": \"credentials\",\n  \"TWITTER_USERNAME\": \"your_username\",\n  \"TWITTER_PASSWORD\": \"your_password\",\n  \"TWITTER_EMAIL\": \"your_email@example.com\", // Optional\n  \"TWITTER_2FA_SECRET\": \"your_2fa_secret\" // Optional, required if 2FA is enabled\n}\n```\n\n#### Twitter API Authentication\n\n```json\n{\n  \"AUTH_METHOD\": \"api\",\n  \"TWITTER_API_KEY\": \"your_api_key\",\n  \"TWITTER_API_SECRET_KEY\": \"your_api_secret_key\",\n  \"TWITTER_ACCESS_TOKEN\": \"your_access_token\",\n  \"TWITTER_ACCESS_TOKEN_SECRET\": \"your_access_token_secret\"\n}\n```\n\n## Available Tools\n\n- `get_user_tweets`: Fetch tweets from a specific user\n- `get_tweet_by_id`: Fetch a specific tweet by ID\n- `search_tweets`: Search for tweets\n- `send_tweet`: Post a new tweet\n- `send_tweet_with_poll`: Post a tweet with a poll\n- `like_tweet`: Like a tweet\n- `retweet`: Retweet a tweet\n- `quote_tweet`: Quote a tweet\n- `get_user_profile`: Get a user's profile\n- `follow_user`: Follow a user\n- `get_followers`: Get a user's followers\n- `get_following`: Get users a user is following\n- `grok_chat`: Chat with Grok via Twitter\n- `health_check`: Check the health of the Twitter MCP server\n\n## Testing Interface\n\nThe MCP includes an interactive command-line interface for testing:\n\n```bash\nnpx agent-twitter-client-mcp-test\n# or if installed locally\nnpm run test:interface\n```\n\nThis launches a REPL where you can test various MCP functions:\n\n```\nagent-twitter-client-mcp> help\n\nAvailable commands:\n  health                     Run a health check\n  profile <username>         Get a user profile\n  tweets <username> [count]  Get tweets from a user\n  tweet <id>                 Get a specific tweet by ID\n  search <query> [count]     Search for tweets\n  post <text>                Post a new tweet\n  like <id>                  Like a tweet\n  retweet <id>               Retweet a tweet\n  quote <id> <text>          Quote a tweet\n  follow <username>          Follow a user\n  followers <userId> [count] Get a user's followers\n  following <userId> [count] Get users a user is following\n  grok <message>             Chat with Grok\n  help                       Show available commands\n  exit                       Exit the test interface\n```\n\n### Example Test Commands\n\n```\n# Run a health check\nagent-twitter-client-mcp> health\n\n# Search for tweets\nagent-twitter-client-mcp> search mcp 2\n\n# Get a user's profile\nagent-twitter-client-mcp> profile elonmusk\n\n# Get tweets from a user\nagent-twitter-client-mcp> tweets openai 5\n\n# Chat with Grok\nagent-twitter-client-mcp> grok Explain quantum computing in simple terms\n```\n\n## Example Usage\n\nAsk Claude to:\n\n- \"Search Twitter for tweets about AI\"\n- \"Post a tweet saying 'Hello from Claude!'\"\n- \"Get the latest tweets from @OpenAI\"\n- \"Chat with Grok about quantum computing\"\n\n## Advanced Usage\n\n### Working with Media\n\nTo post a tweet with an image:\n\n```\nI want to post a tweet with an image. The tweet should say \"Beautiful sunset today!\" and include this image.\n```\n\nTo post a tweet with a video:\n\n```\nI want to post a tweet with a video. The tweet should say \"Check out this amazing video!\" and include the video file.\n```\n\n### Creating Polls\n\nTo create a poll:\n\n```\nCreate a Twitter poll asking \"What's your favorite programming language?\" with options: Python, JavaScript, Rust, and Go. The poll should run for 24 hours.\n```\n\n### Interacting with Grok\n\nTo have a conversation with Grok:\n\n```\nUse Grok to explain quantum computing to me. Ask it to include some real-world applications.\n```\n\nTo continue a conversation with Grok:\n\n```\nContinue the Grok conversation and ask it to elaborate on quantum entanglement.\n```\n\n### Grok's Unique Capabilities\n\nGrok on Twitter has access to real-time Twitter data that even the standalone Grok API doesn't have. This means you can ask Grok about:\n\n- Current trending topics on Twitter\n- Analysis of recent tweets on specific subjects\n- Information about Twitter users and their content\n- Real-time events being discussed on the platform\n\nExample:\n\n```\nUse Grok to analyze the current sentiment around AI on Twitter.\n```\n\n## Troubleshooting\n\n### Authentication Issues\n\n#### Cookie Authentication Problems\n\nIf you're experiencing issues with cookie authentication:\n\n1. **Cookie Expiration**: Twitter cookies typically expire after a certain period. Try refreshing your cookies by logging out and back into Twitter.\n2. **Cookie Format**: Ensure your cookies are properly formatted as a JSON array of strings with the correct domain.\n3. **Required Cookies**: Make sure you've included the essential cookies: `auth_token`, `ct0`, and `twid`.\n\nExample of properly formatted cookies:\n\n```json\n\"TWITTER_COOKIES\": \"[\\\"auth_token=1234567890abcdef; Domain=.twitter.com\\\", \\\"ct0=abcdef1234567890; Domain=.twitter.com\\\", \\\"twid=u%3D1234567890; Domain=.twitter.com\\\"]\"\n```\n\n#### Credential Authentication Problems\n\nIf you're having trouble with username/password authentication:\n\n1. **Two-Factor Authentication**: If your account has 2FA enabled, you'll need to provide the `TWITTER_2FA_SECRET`.\n2. **Account Lockouts**: Too many failed login attempts may lock your account. Check your email for account verification requests.\n3. **Captcha Challenges**: Twitter may present captcha challenges that the client can't handle automatically.\n\n#### API Authentication Problems\n\nFor API authentication issues:\n\n1. **API Key Permissions**: Ensure your API keys have the necessary permissions for the actions you're trying to perform.\n2. **Rate Limiting**: Twitter API has rate limits that may cause failures if exceeded.\n3. **API Changes**: Twitter occasionally changes its API, which may cause compatibility issues.\n\n### Operation Errors\n\n#### Tweet Posting Failures\n\nIf you can't post tweets:\n\n1. **Content Restrictions**: Twitter may block tweets that violate its content policies.\n2. **Media Format Issues**: Ensure media is properly formatted and encoded.\n3. **Rate Limiting**: Twitter limits how frequently you can post.\n\n#### Search Problems\n\nIf search isn't working:\n\n1. **Query Syntax**: Ensure your search query follows Twitter's search syntax.\n2. **Search Limitations**: Some search modes may have restrictions or require specific permissions.\n\n#### Grok Issues\n\nIf Grok functionality isn't working:\n\n1. **Version Requirement**: Grok requires [agent-twitter-client v0.0.19](https://github.com/elizaOS/agent-twitter-client/releases/tag/0.0.19) or higher. The current package uses v0.0.18 for basic functionality.\n2. **Authentication**: Grok requires valid Twitter authentication. Cookie authentication is recommended.\n3. **Rate Limits**: Grok has rate limits (typically 25 messages per 2 hours for non-premium accounts).\n4. **API Changes**: Twitter may change the Grok API endpoints or authentication requirements.\n\n### Server Issues\n\n#### Health Check\n\nUse the `health_check` tool to diagnose server issues:\n\n```\nRun a health check on the agent-twitter-client-mcp server to diagnose any issues.\n```\n\nThe health check will report on:\n\n- Authentication status\n- API connectivity\n- Memory usage\n\n#### Logging\n\nThe server logs to both console and files:\n\n- `error.log`: Contains error-level messages\n- `combined.log`: Contains all log messages\n\nCheck these logs for detailed error information.\n\n## Development\n\n### Prerequisites\n\n- Node.js 18+\n- npm\n\n### Setup\n\n1. Clone the repository\n\n```bash\ngit clone https://github.com/ryanmac/agent-twitter-client-mcp.git\ncd agent-twitter-client-mcp\n```\n\n2. Install dependencies\n\n```bash\nnpm install\n```\n\n3. Create a `.env` file with configuration:\n\n```\nAUTH_METHOD=cookies\nTWITTER_COOKIES=[\"cookie1=value1\", \"cookie2=value2\"]\n```\n\n4. Build the project\n\n```bash\nnpm run build\n```\n\n5. Start the server\n\n```bash\nnpm start\n```\n\n### Environment Variables\n\nIn addition to the authentication variables, you can set:\n\n- `LOG_LEVEL`: Set logging level (error, warn, info, debug)\n- `NODE_ENV`: Set environment (development, production)\n\n## Docker\n\nYou can also run the server using Docker:\n\n### Using Docker Directly\n\n```bash\n# Build the Docker image\ndocker build -t agent-twitter-client-mcp .\n\n# Run the container with environment variables\ndocker run -p 3000:3000 \\\n  -e AUTH_METHOD=cookies \\\n  -e TWITTER_COOKIES='[\"auth_token=YOUR_AUTH_TOKEN; Domain=.twitter.com\", \"ct0=YOUR_CT0_VALUE; Domain=.twitter.com\"]' \\\n  agent-twitter-client-mcp\n```\n\n### Using Docker Compose\n\n1. Create a `.env` file with your Twitter credentials\n2. Run with docker-compose:\n\n```bash\n# Start the service\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f\n\n# Stop the service\ndocker-compose down\n```\n\n### Environment Variables in Docker\n\nYou can pass environment variables to the Docker container in several ways:\n\n1. **In the docker-compose.yml file** (already configured)\n2. **Through a .env file** (recommended for docker-compose)\n3. **Directly in the docker run command** (as shown above)\n\n### Persisting Logs\n\nThe docker-compose configuration includes a volume mount for logs:\n\n```yaml\nvolumes:\n  - ./logs:/app/logs\n```\n\nThis will store logs in a `logs` directory in your project folder.\n\n## Security Considerations\n\n- **Credential Storage**: Store credentials securely, preferably using environment variables or a secure vault.\n- **Rate Limiting**: Implement rate limiting to prevent abuse of the Twitter API.\n- **Content Validation**: Validate all content before posting to prevent malicious use.\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-03fd547adfecb188d9f3dd61c3d66c3f"}