@specstory/tnydev-mcp
v1.0.4
Published
MCP server for tny.dev URL shortening service - AI agent integration for link management
Maintainers
Readme
🚀 Why tny.dev for AI Agents?
Optimized for bursty AI traffic. Right when your agents need them.
Built to handle spikes when agents process batches.
🎯 How Link Shorteners Compare
| Feature | tny.dev | Bitly | Rebrandly | Short.io | TinyURL | |---------|---------|-------|-----------|----------|---------| | First-party MCP Server | ✅ Native | ⚠️ Third-party | ✅ Native | ❌ None | ⚠️ Third-party | | Claude Desktop Extension | ✅ Native .dxt | ❌ None | ❌ None | ❌ None | ❌ None | | Monthly Cost | ✅ $9 | ❌ $199 | ⚠️ $29-35 | ⚠️ $19 | ✅ $9.99 | | Hourly Rate Limit | ✅ 500/hour | ⚠️ ~69/hour* | ⚠️ ~35/hour* | ❌ ~1.4/hour* | ⚠️ ~14/hour* | | Bulk Operations | ✅ 100/request | ❌ Not supported | ✅ 25/request | ✅ 1,000/request | ❌ Not documented |
* Effective hourly rate calculated from monthly quotas divided by 720 hours
🎨 Other Features
- 📱 QR Codes: Automatic QR code generation for all shortened URLs
- 📊 Analytics: Get detailed click analytics for your shortened links
- 📋 Link Management: List all your shortened links with pagination
- 🎯 Rate Limit Awareness: Real-time quota tracking in every response
- 🤖 Natural Language: Built for how AI agents actually work
- 🔗 Custom Domains: Use your own domain for branded short URLs (Developer tier)
- ✨ Custom Slugs: Create memorable short URLs with custom slugs (Developer tier)
🚀 Quick Start
Option 1: Claude Desktop Extension (Easiest)
Installation Steps:
Download the Extension
- Click the button above, or
- Go to Releases and download
tnydev-mcp.dxt
Install in Claude Desktop
- Method 1: Drag and drop the
.dxtfile into Claude Desktop - Method 2: In Claude Desktop, go to Settings → Extensions → Install Extension → Select the
.dxtfile
- Method 1: Drag and drop the
Configure Your API Key
- After installation, click on the extension settings
- Enter your tny.dev API key (get one at tny.dev/account)
- Optionally add your domain ID for custom domains
Start Using
- The tools are now available in your conversation
- Try: "Shorten this URL for me: https://example.com"
Option 2: npm Package (For Developers)
# In your MCP client configuration, use:
npx -y @specstory/tnydev-mcpOption 3: Local Installation
- Get a tny.dev API key from your account settings
- Clone this repository and navigate to
mcp-server - Run:
npm install && npm run build - Set your API key:
echo "TNY_DEV_API_KEY=your_key_here" > .env - Configure your MCP client (see Installation below)
- Start using the tools in your AI assistant!
📋 Prerequisites
For Desktop Extension
- Claude Desktop v0.7.0 or higher
- A tny.dev account with API access
For npm/Manual Installation
- Node.js 18 or higher
- A tny.dev account with API access (developer tier recommended)
- An MCP-compatible client (Claude Desktop, Claude Code, Cursor, or VS Code)
🔑 Getting Started with tny.dev
1. Get Your API Key (30 seconds)
Visit tny.dev → Sign up → Account Settings → Create API Key
2. Choose Your Plan
| Plan | Price | Rate Limit | Best For | |------|-------|------------|----------| | Free | $0 | 50/hour | Testing & personal projects | | Developer | $9/mo | 500/hour | AI agents & automation |
3. Developer Plan Benefits
- ✅ 10x more requests - Handle bursty AI traffic
- ✅ Custom domains - Use your own branded URLs
- ✅ Custom slugs - Create memorable short links
- ✅ Bulk operations - Process up to 100 URLs at once
- ✅ Webhooks - Real-time event notifications
- ✅ Extra API keys - Separate keys for different environments
🌐 Custom Domains (Developer Tier)
To use custom domains with the MCP server:
- Add a Custom Domain: In your tny.dev account, navigate to the Domains section and add your custom domain
- Verify Domain: Complete the DNS verification process
- Get Domain ID: Once verified, copy your domain ID (format:
your_domain_id_here) - Configure MCP Server: Either:
- Set
TNY_DEV_DEFAULT_DOMAIN_IDenvironment variable for global default - Pass
domainIdparameter when creating short URLs - Tool parameter takes precedence over environment variable
- Set
📦 Installation
Local Setup
- Clone or download this repository
- Navigate to the
mcp-serverdirectory:cd mcp-server - Install dependencies:
npm install - Build the TypeScript code:
npm run build - Create your environment file:
cp .env.example .env - Edit
.envand add your tny.dev API key:TNY_DEV_API_KEY=your_api_key_here # Optional: For custom domain support (Developer tier) TNY_DEV_DEFAULT_DOMAIN_ID=your_domain_id_here
🔧 Installation Methods
🚀 Quick Install
🖥️ Claude Desktop Extension (Recommended)
The easiest way to use tny.dev in Claude Desktop:
- Download the latest
tnydev-mcp.dxtfrom Releases - Open Claude Desktop
- Drag and drop the
.dxtfile into Claude Desktop - Configure your API key in the extension settings
- Done! No terminal or JSON editing required
Benefits:
- ✅ One-click installation
- ✅ Automatic updates
- ✅ Secure API key storage
- ✅ User-friendly configuration UI
🛠️ Manual MCP Configuration
For advanced users who prefer manual configuration:
Using npx (Recommended)
Edit your Claude Desktop configuration:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"tny-dev": {
"command": "npx",
"args": ["-y", "@specstory/tnydev-mcp"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}Local installation
{
"mcpServers": {
"tny-dev": {
"command": "node",
"args": ["/absolute/path/to/tinylink/mcp-server/dist/index.js"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}Alternative: Use .env file instead of hardcoding the API key:
{
"mcpServers": {
"tny-dev": {
"command": "node",
"args": ["dist/index.js"],
"cwd": "/absolute/path/to/tinylink/mcp-server"
}
}
}Restart Claude Desktop for changes to take effect.
Using npx (Recommended)
Cursor supports multiple configuration methods:
Method 1: Project-specific configuration
Create .cursor/mcp.json in your project root:
{
"mcpServers": {
"tny-dev": {
"command": "npx",
"args": ["-y", "@specstory/tnydev-mcp"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}Method 2: VS Code settings
Add to your .vscode/settings.json or User Settings:
{
"cursor.mcpServers": {
"tny-dev": {
"command": "npx",
"args": ["-y", "@specstory/tnydev-mcp"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}Local installation
{
"mcpServers": {
"tny-dev": {
"command": "node",
"args": ["/absolute/path/to/tinylink/mcp-server/dist/index.js"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}Note: Restart Cursor after making configuration changes.
Using npx (Recommended)
Add to your Windsurf settings:
{
"mcpServers": {
"tny-dev": {
"command": "npx",
"args": ["-y", "@specstory/tnydev-mcp"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}Local installation
{
"mcpServers": {
"tny-dev": {
"command": "node",
"args": ["/absolute/path/to/tinylink/mcp-server/dist/index.js"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}Using npx (Recommended)
Add to your VSCode settings (.vscode/settings.json or User Settings):
{
"cline.mcpServers": {
"tny-dev": {
"command": "npx",
"args": ["-y", "@specstory/tnydev-mcp"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}Local installation
{
"cline.mcpServers": {
"tny-dev": {
"command": "node",
"args": ["/absolute/path/to/tinylink/mcp-server/dist/index.js"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}For Cursor specifically, you can also create .cursor/mcp.json in your project root:
{
"mcpServers": {
"tny-dev": {
"command": "npx",
"args": ["-y", "@specstory/tnydev-mcp"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}Using npx (Recommended)
Add to your VS Code settings (settings.json):
{
"mcpServers": {
"tny-dev": {
"command": "npx",
"args": ["-y", "@specstory/tnydev-mcp"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}Note: The exact configuration key may vary by extension:
- Continue:
continue.mcpServers - Codeqwen:
codeqwen.mcpServers - Check your extension's documentation for the correct key
Local installation
{
"mcpServers": {
"tny-dev": {
"command": "node",
"args": ["/absolute/path/to/tinylink/mcp-server/dist/index.js"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}Using npx (Recommended)
Add to your Zed settings:
{
"language_models": {
"mcp": {
"servers": {
"tny-dev": {
"command": "npx",
"args": ["-y", "@specstory/tnydev-mcp"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here"
}
}
}
}
}
}Local installation
{
"language_models": {
"mcp": {
"servers": {
"tny-dev": {
"command": "node",
"args": ["/absolute/path/to/tinylink/mcp-server/dist/index.js"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here"
}
}
}
}
}
}Using npx (Recommended)
Add as a locally-scoped server using the CLI:
claude mcp add tny-dev -s local -e TNY_DEV_API_KEY=your_api_key_here -- npx -y @specstory/tnydev-mcpOr create a .mcp.json file in your project root:
{
"mcpServers": {
"tny-dev": {
"command": "npx",
"args": ["-y", "@specstory/tnydev-mcp"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}Local installation
claude mcp add tny-dev -s local -e TNY_DEV_API_KEY=your_api_key_here -- node /absolute/path/to/tinylink/mcp-server/dist/index.jsUsing npx (Recommended)
Add to your Roo Coder settings:
{
"roo.mcpServers": {
"tny-dev": {
"command": "npx",
"args": ["-y", "@specstory/tnydev-mcp"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}Local installation
{
"roo.mcpServers": {
"tny-dev": {
"command": "node",
"args": ["/absolute/path/to/tinylink/mcp-server/dist/index.js"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}Using npx (Recommended)
Add to your Void configuration:
{
"mcpServers": {
"tny-dev": {
"command": "npx",
"args": ["-y", "@specstory/tnydev-mcp"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}Local installation
{
"mcpServers": {
"tny-dev": {
"command": "node",
"args": ["/absolute/path/to/tinylink/mcp-server/dist/index.js"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}Using npx (Recommended)
Most MCP clients support a similar configuration format:
{
"mcpServers": {
"tny-dev": {
"command": "npx",
"args": ["-y", "@specstory/tnydev-mcp"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}Local installation
{
"mcpServers": {
"tny-dev": {
"command": "node",
"args": ["/absolute/path/to/tinylink/mcp-server/dist/index.js"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}Check your client's documentation for the specific configuration file location and format.
🔒 Security Best Practices
Important: Never commit configuration files containing API keys to version control.
Recommended approaches:
Environment Variables (Most Secure)
export TNY_DEV_API_KEY="your_api_key_here" export TNY_DEV_DEFAULT_DOMAIN_ID="your_domain_id_here"Secure Key Storage
- Use a password manager for API keys
- Use system keychain/credential manager
- Use environment-specific
.envfiles (never commit)
Git Security
# Add to .gitignore .env .env.local **/claude_desktop_config.json **/.cursor/mcp.json .vscode/settings.jsonKeys
- Use different keys for different environments
- Monitor key usage in your tny.dev dashboard
💡 AI Agent Use Cases
See how AI assistants naturally use tny.dev in real conversations – no code required:
Traditional API Approach vs. MCP Server
❌ Traditional API Approach
# Step 1: Write code to call API
import requests
def shorten_url(url):
response = requests.post(
'https://www.tny.dev/api/v1/shorten',
headers={
'X-API-Key': 'tnyl_your_api_key_here',
'Content-Type': 'application/json'
},
json={'url': url}
)
return response.json()
# Step 2: Process each link manually
links = [...] # Your list of links
shortened = [shorten_url(link) for link in links]
# Step 3: Format and organize results
# More code needed...✅ With tny.dev MCP Server
💬 You: "I'm writing a blog post about React
hooks. Please shorten these documentation
links and organize them by hook type."
🤖 Claude: "I'll shorten those React
documentation links and organize them by
hook type for you..."
[Automatically processes all links using MCP]No code required! Just natural conversation.
Common AI Agent Workflows
📊 Campaign Analytics
"Show me which links from yesterday's campaign got the most clicks"
⚡ Bulk Processing
"Shorten all the URLs in this documentation and create a table of contents"
🛡️ Link Management
"Update all campaign links to use our new landing page"
🎯 Smart Organization
"Group these product links by category and create trackable short URLs for each"
🛠️ Available Tools
For detailed API documentation, visit the tny.dev API Docs.
1. shorten_url
Create a shortened URL with support for custom domains and slugs (Developer tier feature).
Parameters:
url(required): The URL to shortencustomSlug(optional): Custom slug for the short URL (3-50 chars, alphanumeric + hyphens/underscores) - requires domainIddomainId(optional): Domain ID for custom domain usage - required when using customSlug
Examples:
# Basic usage
Use the shorten_url tool to create a short link for https://example.com/very/long/url
# With custom domain and slug
Use the shorten_url tool to create a short link for https://example.com with customSlug "my-link" and domainId "your_domain_id_here"
# With custom domain only (random slug)
Use the shorten_url tool to create a short link for https://example.com with domainId "your_domain_id_here"Note: Custom domains and slugs require a Developer tier subscription. You can configure a default domain ID using the TNY_DEV_DEFAULT_DOMAIN_ID environment variable.
2. get_link_analytics
Get click analytics for a shortened link.
Parameters:
slug(required): The slug of the shortened URL
Example:
Get analytics for the link with slug "abc123"3. list_links
List all shortened links created with your API key.
Parameters:
page(optional): Page number (default: 1)limit(optional): Number of links per page (1-100, default: 20)
Example:
Show me all my shortened links⚡ Rate Limits & Pricing
Simple, Transparent Pricing
| | Free | Developer | |---|---|---| | Monthly Cost | $0 | $9 | | Hourly Rate Limit | 50/hour | 500/hour | | Effective Cost | - | $0.018/request | | Compared to Bitly | - | 95% cheaper |
💡 Pro Tip: The server displays remaining quota in each response to help you track usage in real-time.
⚙️ Configuration Examples
{
"mcpServers": {
"tny-dev": {
"command": "npx",
"args": ["-y", "@specstory/tnydev-mcp"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here" // Optional
}
}
}
}{
"mcpServers": {
"tny-dev": {
"command": "npx",
"args": ["-y", "@specstory/tnydev-mcp"],
"env": {
"TNY_DEV_API_KEY": "your_api_key_here",
"TNY_DEV_DEFAULT_DOMAIN_ID": "your_domain_id_here"
}
}
}
}{
"mcpServers": {
"tny-dev": {
"command": "node",
"args": ["dist/index.js"],
"cwd": "/path/to/tinylink/mcp-server",
"env": {
"DEBUG": "true",
"TNY_DEV_BASE_URL": "https://staging.tny.dev/api/v1" // Optional staging URL
}
}
}
}{
"mcpServers": {
"tny-dev-prod": {
"command": "npx",
"args": ["-y", "@specstory/tnydev-mcp"],
"env": {
"TNY_DEV_API_KEY": "prod_key_here"
}
},
"tny-dev-test": {
"command": "npx",
"args": ["-y", "@specstory/tnydev-mcp"],
"env": {
"TNY_DEV_API_KEY": "test_key_here",
"TNY_DEV_BASE_URL": "https://staging.tny.dev/api/v1"
}
}
}
}🔨 Development
Prerequisites for Development
- Node.js 18+
- npm or yarn
- TypeScript knowledge
Setup
# Clone the repository
git clone https://github.com/yourusername/tinylink.git
cd tinylink/mcp-server
# Install dependencies
npm install
# Copy environment template
cp .env.example .env
# Add your API key to .env
echo "TNY_DEV_API_KEY=your_key_here" >> .env
# Build the project
npm run buildDevelopment Commands
# Run in development mode with auto-reload
npm run dev
# Build the project
npm run build
# Run linting
npm run lint
# Run type checking
npm run typecheck
# Start the built server
npm startTesting the Server
# Test manually with debug output
DEBUG=true TNY_DEV_API_KEY=your_key node dist/index.js
# Test with a custom base URL
TNY_DEV_BASE_URL=https://staging.tny.dev/api/v1 npm startProject Structure
mcp-server/
├── src/
│ ├── index.ts # Main server entry point
│ ├── client.ts # API client implementation
│ ├── types.ts # TypeScript type definitions
│ └── handlers/ # Tool handlers
│ ├── shorten.ts # URL shortening handler
│ ├── analytics.ts # Analytics handler
│ └── links.ts # Links listing handler
├── dist/ # Compiled JavaScript (generated)
├── package.json # Project configuration
├── tsconfig.json # TypeScript configuration
├── .env.example # Environment template
└── README.md # This file🐛 Troubleshooting
Server Not Appearing in Client
- ✅ Ensure the configuration file is valid JSON (check for trailing commas)
- ✅ Verify the absolute path to the server is correct
- ✅ Check that Node.js is installed and in your system PATH
- ✅ Restart your client application after configuration changes
- ✅ Enable debug mode:
DEBUG=truein environment
API Key Issues
- ✅ Verify your API key is correctly set in the configuration or
.envfile - ✅ Check that your API key is active in your Account settings
- ✅ Ensure there are no extra spaces or quotes around the API key
- ✅ Test the server manually:
TNY_DEV_API_KEY=your_key node dist/index.js
Connection Errors
- ✅ Run
npm run buildto ensure the server is compiled - ✅ Check for error messages in the client's developer console
- ✅ Try running the server standalone to see error output
- ✅ Verify Node.js version is 18 or higher:
node --version
Rate Limit Errors
- ℹ️ The server displays remaining quota in each response
- ℹ️ Free tier: 50 requests/hour, Developer tier: 500 requests/hour
- ℹ️ Rate limits reset every hour from first request
- ℹ️ Consider upgrading at tny.dev Plans
Configuration File Location
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
Common Issues
- Server not loading: Check Claude Desktop logs in Console.app (macOS) or Event Viewer (Windows)
- Permission denied: Ensure Claude Desktop has permission to execute Node.js
- Path issues: Use absolute paths, avoid
~or environment variables in paths
Configuration Priority
.cursor/mcp.json(project-specific)- VS Code User Settings
- VS Code Workspace Settings
Common Issues
- Multiple configs: Check all possible config locations
- Extension conflicts: Disable other MCP extensions temporarily
- Reload required: Use Command Palette > "Developer: Reload Window"
Finding the Right Config Key
- Continue:
continue.mcpServers - Codeqwen:
codeqwen.mcpServers - Cline:
cline.mcpServers - Check extension docs for exact key
Common Issues
- Settings sync: Disable settings sync temporarily if having issues
- Extension updates: Ensure extensions are up to date
- Workspace trust: Ensure workspace is trusted
macOS/Linux
- ✅ Ensure execute permissions:
chmod +x dist/index.js - ✅ Check
.envfile permissions:chmod 600 .env - ✅ Use full paths, not
~/in configurations
Windows
- ✅ Use forward slashes or double backslashes:
C:/path/to/serverorC:\\path\\to\\server - ✅ Run as Administrator if permission issues persist
- ✅ Ensure Node.js is in system PATH, not just user PATH
- ✅ If using WSL, use Windows paths in config, not WSL paths
Docker/Dev Containers
- ✅ Mount the MCP server directory as a volume
- ✅ Ensure Node.js is installed in the container
- ✅ Use container paths in configuration
📄 License
MIT
📦 Downloads & Releases
Desktop Extension (.dxt)
- Latest Release: Download tnydev-mcp.dxt
- All Releases: GitHub Releases
- Auto-Updates: Extensions update automatically in Claude Desktop
npm Package
- Package: @specstory/tnydev-mcp
- Install:
npm install -g @specstory/tnydev-mcp - Direct Use:
npx @specstory/tnydev-mcp
📚 Resources
Documentation
Community
Related Projects
💬 Support
Getting Help
| Issue Type | Where to Get Help | |------------|-------------------| | 🐛 MCP Server Issues | GitHub Issues | | 🔑 API/Account Issues | tny.dev Support | | 📱 Claude Desktop | Claude Help Center | | 💻 Client-Specific | Check client's documentation |
Quick Links
- Status Page: status.tny.dev
- API Status: Check the tny.dev Status Page
- Account Dashboard: tny.dev/account
🚀 Ready for Agent-First Development?
🤝 Contributing
We welcome contributions! Please see our Contributing Guide for details.
Development Workflow
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
🙏 Acknowledgments
- Built with Model Context Protocol SDK
- Powered by tny.dev - The API-first link shortener built for AI agents
- Compatible with Claude and other MCP clients
